The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs(skills): regenerate skill pages and the prompt-surface snapshot
Teknium08a7c25eecb6
diff --git a/tests/fixtures/prompt_surface/prompts/cli-code.claude.txt b/tests/fixtures/prompt_surface/prompts/cli-code.claude.txtindex cb7a4ab3d51..abf697e5e0f 100644--- a/tests/fixtures/prompt_surface/prompts/cli-code.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/cli-code.claude.txt@@ -61,13 +61,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -76,40 +74,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/cli.claude.txt b/tests/fixtures/prompt_surface/prompts/cli.claude.txtindex 5323d92202c..f0cedf661f0 100644--- a/tests/fixtures/prompt_surface/prompts/cli.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/cli.claude.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/cli.gemini.txt b/tests/fixtures/prompt_surface/prompts/cli.gemini.txtindex 6be52658133..38c9030496e 100644--- a/tests/fixtures/prompt_surface/prompts/cli.gemini.txt+++ b/tests/fixtures/prompt_surface/prompts/cli.gemini.txt@@ -51,13 +51,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -66,40 +64,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/cli.gpt.txt b/tests/fixtures/prompt_surface/prompts/cli.gpt.txtindex e5509bef7f0..62866d5b17b 100644--- a/tests/fixtures/prompt_surface/prompts/cli.gpt.txt+++ b/tests/fixtures/prompt_surface/prompts/cli.gpt.txt@@ -102,13 +102,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -117,40 +115,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/cli.hermes.txt b/tests/fixtures/prompt_surface/prompts/cli.hermes.txtindex b745e8cc9ae..c12fbc23ab1 100644--- a/tests/fixtures/prompt_surface/prompts/cli.hermes.txt+++ b/tests/fixtures/prompt_surface/prompts/cli.hermes.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/cron.claude.txt b/tests/fixtures/prompt_surface/prompts/cron.claude.txtindex 25d4d8ea4df..f9f7655c501 100644--- a/tests/fixtures/prompt_surface/prompts/cron.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/cron.claude.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/desktop.claude.txt b/tests/fixtures/prompt_surface/prompts/desktop.claude.txtindex def55c12279..1080f10f258 100644--- a/tests/fixtures/prompt_surface/prompts/desktop.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/desktop.claude.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/discord.claude.txt b/tests/fixtures/prompt_surface/prompts/discord.claude.txtindex feefab33e1b..62fab949a72 100644--- a/tests/fixtures/prompt_surface/prompts/discord.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/discord.claude.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/prompts/telegram.claude.txt b/tests/fixtures/prompt_surface/prompts/telegram.claude.txtindex ac952ff0f52..733277cad5b 100644--- a/tests/fixtures/prompt_surface/prompts/telegram.claude.txt+++ b/tests/fixtures/prompt_surface/prompts/telegram.claude.txt@@ -37,13 +37,11 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loaded- codex: Delegate coding to OpenAI Codex CLI (features, PRs).- computer-use: Drive the desktop background-first; escalate on signal.- hermes-agent: Use, configure, theme, extend, and orchestrate Hermes Agent.- - opencode: Delegate coding to OpenCode CLI (features, PR review).creative:- architecture-diagram: Dark-themed SVG architecture/cloud/infra diagrams as HTML.- ascii-video: ASCII video: convert video/audio to colored ASCII MP4/GIF.- baoyu-infographic: Infographics: 21 layouts x 21 styles (信息图, 可视化).- claude-design: Design one-off HTML artifacts (landing, deck, prototype).- - design-md: Author/validate/export Google's DESIGN.md token spec files.- humanizer: Humanize text: strip AI-isms and add real voice.- manim-video: Manim CE animations: 3Blue1Brown math/algo videos.- p5js: p5.js sketches: gen art, shaders, interactive, 3D.@@ -52,40 +50,27 @@ After difficult/iterative tasks, offer to save as a skill. If a skill you loadedemail:- email-inbox-triage: Triage an inbox: prioritize threads, draft replies safely.- himalaya: Himalaya CLI: IMAP/SMTP email from terminal.- media:- - gif-search: Search/download GIFs from Tenor via curl + jq.- - songsee: Audio spectrograms/features (mel, chroma, MFCC) via CLI.- - youtube-content: YouTube transcripts to summaries, threads, blogs.+ - youtube-content: YouTube transcripts to summaries, threads, blogs.- obsidian: Read, search, create, and edit notes in the Obsidian vault.productivity:- - airtable: Airtable REST API via curl. Records CRUD, filters, upserts.- - box: Box manages cloud files, sharing, search, and metadata.- document-to-action-items: Extract cited obligations, deadlines, tasks from documents.- - docx: Create, read, edit, template, and review Word .docx files.- google-workspace: Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.- maps: Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.- meeting-action-items: Turn meeting notes into cited decisions, owners, tickets.- - notion: Notion API + ntn CLI: pages, databases, markdown, Workers.+ - microsoft-office: Create, read, and edit Word, PowerPoint, and Excel files.- pdf: PDF files: create, read, merge, fill, OCR, edit text.- - powerpoint: Create, read, edit .pptx decks with python-pptx.- product-price-monitor: Watch product, flight, or listing prices; alert on target.- teams-meeting-pipeline: Teams meeting summaries, job replay, Graph subscriptions.- weekly-review-planning: Weekly reset: commitments, stalled work, next-week plan.- - xlsx: Create, read, edit Excel .xlsx workbooks and CSVs.research:- arxiv: Search arXiv papers by keyword, author, category, or ID.- competitor-news-monitor: Watch named companies for material news; cited digests.- grounded-citations: Ground answers and documents in cited, verifiable sources.- - llm-wiki: Karpathy's LLM Wiki: build/query interlinked markdown KB.- xurl: X/Twitter via xurl CLI: raw post search, posting, DM, media.software-development:- codebase-inspection: Inspect codebases w/ pygount: LOC, languages, ratios.- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.- github: GitHub via gh CLI: PRs, issues, reviews, repos, auth.- - hermes-agent-skill-authoring: Author in-repo SKILL.md files: frontmatter and structure.- - inspecting-hermes-desktop-dom: Read the live Hermes desktop DOM/CSS over CDP.- - node-inspect-debugger: Debug Node.js via --inspect + Chrome DevTools Protocol CLI.- - python-debugpy: Debug Python: pdb REPL + debugpy remote (DAP).- requesting-code-review: Pre-commit review: security scan, quality gates, auto-fix.- simplify-code: Parallel 4-agent cleanup of recent code changes.- spike: Throwaway experiments to validate an idea before build.diff --git a/tests/fixtures/prompt_surface/surfaces.json b/tests/fixtures/prompt_surface/surfaces.jsonindex 04c38c12ebd..b708de40930 100644--- a/tests/fixtures/prompt_surface/surfaces.json+++ b/tests/fixtures/prompt_surface/surfaces.json@@ -3,7 +3,7 @@"prompt_tokens": {"context": 134,"stable": 1829,- "volatile": 1528+ "volatile": 1268},"tool_tokens": 11242,"tools": [@@ -36,7 +36,7 @@"prompt_tokens": {"context": 0,"stable": 1225,- "volatile": 1528+ "volatile": 1268},"tool_tokens": 11242,"tools": [@@ -69,7 +69,7 @@"prompt_tokens": {"context": 0,"stable": 1646,- "volatile": 1527+ "volatile": 1266},"tool_tokens": 11242,"tools": [@@ -102,7 +102,7 @@"prompt_tokens": {"context": 0,"stable": 2420,- "volatile": 1524+ "volatile": 1264},"tool_tokens": 11398,"tools": [@@ -135,7 +135,7 @@"prompt_tokens": {"context": 0,"stable": 1225,- "volatile": 1528+ "volatile": 1268},"tool_tokens": 11242,"tools": [@@ -168,7 +168,7 @@"prompt_tokens": {"context": 0,"stable": 1211,- "volatile": 1528+ "volatile": 1268},"tool_tokens": 11242,"tools": [@@ -201,7 +201,7 @@"prompt_tokens": {"context": 0,"stable": 1473,- "volatile": 1529+ "volatile": 1269},"tool_tokens": 11898,"tools": [@@ -235,7 +235,7 @@"prompt_tokens": {"context": 0,"stable": 1244,- "volatile": 1529+ "volatile": 1269},"tool_tokens": 11242,"tools": [@@ -268,7 +268,7 @@"prompt_tokens": {"context": 0,"stable": 1276,- "volatile": 1529+ "volatile": 1269},"tool_tokens": 11242,"tools": [diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.mdindex 5351974c741..b6a9115984c 100644--- a/website/docs/reference/optional-skills-catalog.md+++ b/website/docs/reference/optional-skills-catalog.md@@ -37,6 +37,7 @@ hermes skills uninstall <skill-name>| [**dynamic-workflow**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md) | Plan-in-code fan-outs, adversarial verification, waves. || [**grok**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md) | Delegate coding to xAI Grok Build CLI (features, PRs). || [**honcho**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md) | Configure and troubleshoot Honcho memory for Hermes. |+| [**opencode**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-opencode.md) | Delegate coding to OpenCode CLI (features, PR review). || [**openhands**](../user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). |## blockchain@@ -61,7 +62,6 @@ hermes skills uninstall <skill-name>| [**anatomy**](../user-guide/skills/optional/creative/creative-anatomy.md) | Explain an idea as an interactive isometric machine figure. || [**archify**](../user-guide/skills/optional/creative/creative-archify.md) | Validated interactive HTML diagrams, upstream-maintained. || [**ascii-art**](../user-guide/skills/optional/creative/creative-ascii-art.md) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. |-| [**audiocraft-audio-generation**](../user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. || [**auteur**](../user-guide/skills/optional/creative/creative-auteur.md) | Design and build cinematic, award-level web pages. || [**baoyu-article-illustrator**](../user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md) | Article illustrations: type × style × palette consistency. || [**baoyu-comic**](../user-guide/skills/optional/creative/creative-baoyu-comic.md) | Knowledge comics (知识漫画): educational, biography, tutorial. |@@ -70,6 +70,7 @@ hermes skills uninstall <skill-name>| [**comfyui**](../user-guide/skills/optional/creative/creative-comfyui.md) | Generate images, video, and audio via diffusion workflows. || [**concept-diagrams**](../user-guide/skills/optional/creative/creative-concept-diagrams.md) | Generate flat, minimal educational SVG visuals as HTML. || [**creative-ideation**](../user-guide/skills/optional/creative/creative-creative-ideation.md) | Generate ideas via named methods from creative practice. |+| [**design-md**](../user-guide/skills/optional/creative/creative-design-md.md) | Author/validate/export Google's DESIGN.md token spec files. || [**draw-your-font**](../user-guide/skills/optional/creative/creative-draw-your-font.md) | Turn a handwriting photo into an installable TTF font. || [**dream-loop**](../user-guide/skills/optional/creative/creative-dream-loop.md) | Build stunning 3D scenes via a concept-art fidelity loop. || [**excalidraw**](../user-guide/skills/optional/creative/creative-excalidraw.md) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). |@@ -155,6 +156,13 @@ hermes skills uninstall <skill-name>| [**mcp-oauth-remote-gateway**](../user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md) | Manual OAuth for remote MCP servers on headless gateways. || [**mcporter**](../user-guide/skills/optional/mcp/mcp-mcporter.md) | List, auth, and call MCP servers/tools from the terminal. |+## media++| Skill | Description |+|-------|-------------|+| [**gif-search**](../user-guide/skills/optional/media/media-gif-search.md) | Search/download GIFs from Tenor via curl + jq. |+| [**songsee**](../user-guide/skills/optional/media/media-songsee.md) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. |+## mlops| Skill | Description |@@ -162,39 +170,26 @@ hermes skills uninstall <skill-name>| [**accelerate**](../user-guide/skills/optional/mlops/mlops-accelerate.md) | Run PyTorch training across GPUs with minimal changes. || [**axolotl**](../user-guide/skills/optional/mlops/mlops-training-axolotl.md) | Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). || [**chroma**](../user-guide/skills/optional/mlops/mlops-chroma.md) | Embedding database for RAG and semantic search. |-| [**clip**](../user-guide/skills/optional/mlops/mlops-clip.md) | Zero-shot image classification and image-text search. || [**dspy**](../user-guide/skills/optional/mlops/mlops-research-dspy.md) | DSPy: declarative LM programs, auto-optimize prompts, RAG. || [**evaluating-llms-harness**](../user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). || [**faiss**](../user-guide/skills/optional/mlops/mlops-faiss.md) | Fast vector similarity search at billion scale. || [**flash-attention**](../user-guide/skills/optional/mlops/mlops-flash-attention.md) | Speed up long-sequence transformer training and inference. |-| [**guidance**](../user-guide/skills/optional/mlops/mlops-guidance.md) | Constrain LLM output with grammars; guarantee valid JSON. |-| [**huggingface-hub**](../user-guide/skills/optional/mlops/mlops-models-huggingface-hub.md) | HuggingFace hf CLI: search/download/upload models, datasets. |-| [**huggingface-tokenizers**](../user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md) | Fast BPE/WordPiece tokenization and custom vocab training. |-| [**instructor**](../user-guide/skills/optional/mlops/mlops-instructor.md) | Structured LLM outputs validated with Pydantic. || [**lambda-labs**](../user-guide/skills/optional/mlops/mlops-lambda-labs.md) | On-demand GPU cloud instances for ML training. || [**llama-cpp**](../user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md) | llama.cpp local GGUF inference + HF Hub model discovery. |-| [**llava**](../user-guide/skills/optional/mlops/mlops-llava.md) | Vision-language chat: VQA, captioning, image dialogue. || [**modal**](../user-guide/skills/optional/mlops/mlops-modal.md) | Serverless GPU cloud for ML jobs and model APIs. || [**nemo-curator**](../user-guide/skills/optional/mlops/mlops-nemo-curator.md) | Curate LLM training data: dedupe, filter, PII redaction. || [**obliteratus**](../user-guide/skills/optional/mlops/mlops-obliteratus.md) | OBLITERATUS: abliterate LLM refusals (diff-in-means). |-| [**outlines**](../user-guide/skills/optional/mlops/mlops-inference-outlines.md) | Outlines: structured JSON/regex/Pydantic LLM generation. || [**peft**](../user-guide/skills/optional/mlops/mlops-peft.md) | Fine-tune large LLMs with LoRA on limited GPU memory. |-| [**pinecone**](../user-guide/skills/optional/mlops/mlops-pinecone.md) | Managed vector DB for production RAG and search. || [**pytorch-fsdp**](../user-guide/skills/optional/mlops/mlops-pytorch-fsdp.md) | Fully sharded data-parallel training for large models. || [**pytorch-lightning**](../user-guide/skills/optional/mlops/mlops-pytorch-lightning.md) | Clean training loops with built-in distributed support. |-| [**qdrant**](../user-guide/skills/optional/mlops/mlops-qdrant.md) | Vector search engine for production RAG systems. || [**saelens**](../user-guide/skills/optional/mlops/mlops-saelens.md) | Train sparse autoencoders to interpret model features. || [**segment-anything-model**](../user-guide/skills/optional/mlops/mlops-models-segment-anything-model.md) | SAM: zero-shot image segmentation via points, boxes, masks. || [**serving-llms-vllm**](../user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm.md) | vLLM: high-throughput LLM serving, OpenAI API, quantization. || [**simpo**](../user-guide/skills/optional/mlops/mlops-simpo.md) | Reference-free preference alignment, simpler than DPO. || [**slime**](../user-guide/skills/optional/mlops/mlops-slime.md) | RL post-training for LLMs with Megatron and SGLang. |-| [**stable-diffusion**](../user-guide/skills/optional/mlops/mlops-stable-diffusion.md) | Text-to-image generation, inpainting, and img2img. || [**tensorrt-llm**](../user-guide/skills/optional/mlops/mlops-tensorrt-llm.md) | High-throughput LLM inference on NVIDIA GPUs. || [**torchtitan**](../user-guide/skills/optional/mlops/mlops-torchtitan.md) | Pretrain LLMs at scale with PyTorch 4D parallelism. |-| [**trl-fine-tuning**](../user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md) | TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF. || [**unsloth**](../user-guide/skills/optional/mlops/mlops-training-unsloth.md) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. |-| [**weights-and-biases**](../user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md) | W&B: log ML experiments, sweeps, model registry, dashboards. |-| [**whisper**](../user-guide/skills/optional/mlops/mlops-whisper.md) | Transcribe and translate speech in 99 languages. |## payments@@ -208,11 +203,14 @@ hermes skills uninstall <skill-name>| Skill | Description ||-------|-------------|+| [**airtable**](../user-guide/skills/optional/productivity/productivity-airtable.md) | Airtable REST API via curl. Records CRUD, filters, upserts. |+| [**box**](../user-guide/skills/optional/productivity/productivity-box.md) | Box manages cloud files, sharing, search, and metadata. || [**canvas**](../user-guide/skills/optional/productivity/productivity-canvas.md) | Fetch Canvas LMS courses and assignments via API token. || [**decision-questionnaire**](../user-guide/skills/optional/productivity/productivity-decision-questionnaire.md) | Turn an unanswerable decision into a questionnaire doc. || [**here-now**](../user-guide/skills/optional/productivity/productivity-here-now.md) | Publish sites to {slug}.here.now and store files in Drives. || [**live-dashboard**](../user-guide/skills/optional/productivity/productivity-live-dashboard.md) | Build self-updating dashboards from live sources. || [**memento-flashcards**](../user-guide/skills/optional/productivity/productivity-memento-flashcards.md) | Spaced-repetition flashcards: create, review, quiz, export. |+| [**notion**](../user-guide/skills/optional/productivity/productivity-notion.md) | Notion API + ntn CLI: pages, databases, markdown, Workers. || [**property-listings**](../user-guide/skills/optional/productivity/productivity-property-listings.md) | Present property and rental listings as desktop cards. || [**shop**](../user-guide/skills/optional/productivity/productivity-shop.md) | Shop catalog search, checkout, order tracking, returns. || [**shopify**](../user-guide/skills/optional/productivity/productivity-shopify.md) | Query Shopify Admin/Storefront GraphQL APIs via curl. |@@ -230,9 +228,9 @@ hermes skills uninstall <skill-name>| [**drug-discovery**](../user-guide/skills/optional/research/research-drug-discovery.md) | Drug discovery: ChEMBL search, drug-likeness, interactions. || [**duckduckgo-search**](../user-guide/skills/optional/research/research-duckduckgo-search.md) | Free keyless web, news, and image search via ddgs. || [**gitnexus-explorer**](../user-guide/skills/optional/research/research-gitnexus-explorer.md) | Serve an interactive codebase knowledge graph web UI. |+| [**llm-wiki**](../user-guide/skills/optional/research/research-llm-wiki.md) | Karpathy's LLM Wiki: build/query interlinked markdown KB. || [**osint-investigation**](../user-guide/skills/optional/research/research-osint-investigation.md) | Follow the money via public records and sanctions data. || [**parallel-cli**](../user-guide/skills/optional/research/research-parallel-cli.md) | Agent-native web search, deep research, and enrichment. |-| [**pinecone-research**](../user-guide/skills/optional/research/research-pinecone-research.md) | Agent RAG and long-term memory with Pinecone. || [**qmd**](../user-guide/skills/optional/research/research-qmd.md) | Hybrid local search over notes, docs, and transcripts. || [**research-paper-writing**](../user-guide/skills/optional/research/research-research-paper-writing.md) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. || [**rss-feeds**](../user-guide/skills/optional/research/research-rss-feeds.md) | Read RSS, Atom, JSON feeds; discover feeds behind a page. |@@ -269,7 +267,11 @@ hermes skills uninstall <skill-name>| [**ast-grep**](../user-guide/skills/optional/software-development/software-development-ast-grep.md) | AST-aware structural code search and rewrite via ast-grep. || [**code-wiki**](../user-guide/skills/optional/software-development/software-development-code-wiki.md) | Generate wiki docs + Mermaid diagrams for any codebase. || [**grill-me**](../user-guide/skills/optional/software-development/software-development-grill-me.md) | Adversarial plan interview before implementation. |+| [**hermes-agent-skill-authoring**](../user-guide/skills/optional/software-development/software-development-hermes-agent-skill-authoring.md) | Author in-repo SKILL.md files: frontmatter and structure. |+| [**inspecting-hermes-desktop-dom**](../user-guide/skills/optional/software-development/software-development-inspecting-hermes-desktop-dom.md) | Read the live Hermes desktop DOM/CSS over CDP. |+| [**node-inspect-debugger**](../user-guide/skills/optional/software-development/software-development-node-inspect-debugger.md) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. || [**pr-lens**](../user-guide/skills/optional/software-development/software-development-pr-lens.md) | Draw code changes as animated architecture/data-flow SVGs. |+| [**python-debugpy**](../user-guide/skills/optional/software-development/software-development-python-debugpy.md) | Debug Python: pdb REPL + debugpy remote (DAP). || [**rest-graphql-debug**](../user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md) | Debug REST/GraphQL APIs: status codes, auth, schemas, repro. || [**subagent-driven-development**](../user-guide/skills/optional/software-development/software-development-subagent-driven-development.md) | Execute plans via delegate_task subagents (2-stage review). |diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.mdindex 0c17cbbd927..96d45c9ef33 100644--- a/website/docs/reference/skills-catalog.md+++ b/website/docs/reference/skills-catalog.md@@ -29,7 +29,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg| [`codex`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents/codex` || [`computer-use`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md) | Drive the desktop background-first; escalate on signal. | `autonomous-ai-agents/computer-use` || [`hermes-agent`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents/hermes-agent` |-| [`opencode`](../user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents/opencode` |## creative@@ -39,7 +38,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg| [`ascii-video`](../user-guide/skills/bundled/creative/creative-ascii-video.md) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative/ascii-video` || [`baoyu-infographic`](../user-guide/skills/bundled/creative/creative-baoyu-infographic.md) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` || [`claude-design`](../user-guide/skills/bundled/creative/creative-claude-design.md) | Design one-off HTML artifacts (landing, deck, prototype). | `creative/claude-design` |-| [`design-md`](../user-guide/skills/bundled/creative/creative-design-md.md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` || [`humanizer`](../user-guide/skills/bundled/creative/creative-humanizer.md) | Humanize text: strip AI-isms and add real voice. | `creative/humanizer` || [`manim-video`](../user-guide/skills/bundled/creative/creative-manim-video.md) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative/manim-video` || [`p5js`](../user-guide/skills/bundled/creative/creative-p5js.md) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative/p5js` |@@ -63,8 +61,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg| Skill | Description | Path ||-------|-------------|------|-| [`gif-search`](../user-guide/skills/bundled/media/media-gif-search.md) | Search/download GIFs from Tenor via curl + jq. | `media/gif-search` |-| [`songsee`](../user-guide/skills/bundled/media/media-songsee.md) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media/songsee` || [`youtube-content`](../user-guide/skills/bundled/media/media-youtube-content.md) | YouTube transcripts to summaries, threads, blogs. | `media/youtube-content` |## note-taking@@ -77,20 +73,15 @@ If a skill is missing from this list but present in the repo, the catalog is reg| Skill | Description | Path ||-------|-------------|------|-| [`airtable`](../user-guide/skills/bundled/productivity/productivity-airtable.md) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity/airtable` |-| [`box`](../user-guide/skills/bundled/productivity/productivity-box.md) | Box manages cloud files, sharing, search, and metadata. | `productivity/box` || [`document-to-action-items`](../user-guide/skills/bundled/productivity/productivity-document-to-action-items.md) | Extract cited obligations, deadlines, tasks from documents. | `productivity/document-to-action-items` |-| [`docx`](../user-guide/skills/bundled/productivity/productivity-docx.md) | Create, read, edit, template, and review Word .docx files. | `productivity/docx` || [`google-workspace`](../user-guide/skills/bundled/productivity/productivity-google-workspace.md) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity/google-workspace` || [`maps`](../user-guide/skills/bundled/productivity/productivity-maps.md) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity/maps` || [`meeting-action-items`](../user-guide/skills/bundled/productivity/productivity-meeting-action-items.md) | Turn meeting notes into cited decisions, owners, tickets. | `productivity/meeting-action-items` |-| [`notion`](../user-guide/skills/bundled/productivity/productivity-notion.md) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity/notion` |+| [`microsoft-office`](../user-guide/skills/bundled/productivity/productivity-microsoft-office.md) | Create, read, and edit Word, PowerPoint, and Excel files. | `productivity/microsoft-office` || [`pdf`](../user-guide/skills/bundled/productivity/productivity-pdf.md) | PDF files: create, read, merge, fill, OCR, edit text. | `productivity/pdf` |-| [`powerpoint`](../user-guide/skills/bundled/productivity/productivity-powerpoint.md) | Create, read, edit .pptx decks with python-pptx. | `productivity/powerpoint` || [`product-price-monitor`](../user-guide/skills/bundled/productivity/productivity-product-price-monitor.md) | Watch product, flight, or listing prices; alert on target. | `productivity/product-price-monitor` || [`teams-meeting-pipeline`](../user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity/teams-meeting-pipeline` || [`weekly-review-planning`](../user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md) | Weekly reset: commitments, stalled work, next-week plan. | `productivity/weekly-review-planning` |-| [`xlsx`](../user-guide/skills/bundled/productivity/productivity-xlsx.md) | Create, read, edit Excel .xlsx workbooks and CSVs. | `productivity/xlsx` |## research@@ -99,7 +90,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg| [`arxiv`](../user-guide/skills/bundled/research/research-arxiv.md) | Search arXiv papers by keyword, author, category, or ID. | `research/arxiv` || [`competitor-news-monitor`](../user-guide/skills/bundled/research/research-competitor-news-monitor.md) | Watch named companies for material news; cited digests. | `research/competitor-news-monitor` || [`grounded-citations`](../user-guide/skills/bundled/research/research-grounded-citations.md) | Ground answers and documents in cited, verifiable sources. | `research/grounded-citations` |-| [`llm-wiki`](../user-guide/skills/bundled/research/research-llm-wiki.md) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research/llm-wiki` |## social-media@@ -114,10 +104,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg| [`codebase-inspection`](../user-guide/skills/bundled/software-development/software-development-codebase-inspection.md) | Inspect codebases w/ pygount: LOC, languages, ratios. | `software-development/codebase-inspection` || [`dogfood`](../user-guide/skills/bundled/software-development/software-development-dogfood.md) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development/dogfood` || [`github`](../user-guide/skills/bundled/software-development/software-development-github.md) | GitHub via gh CLI: PRs, issues, reviews, repos, auth. | `software-development/github` |-| [`hermes-agent-skill-authoring`](../user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development/hermes-agent-skill-authoring` |-| [`inspecting-hermes-desktop-dom`](../user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development/inspecting-hermes-desktop-dom` |-| [`node-inspect-debugger`](../user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development/node-inspect-debugger` |-| [`python-debugpy`](../user-guide/skills/bundled/software-development/software-development-python-debugpy.md) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development/python-debugpy` || [`requesting-code-review`](../user-guide/skills/bundled/software-development/software-development-requesting-code-review.md) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development/requesting-code-review` || [`simplify-code`](../user-guide/skills/bundled/software-development/software-development-simplify-code.md) | Parallel 4-agent cleanup of recent code changes. | `software-development/simplify-code` || [`spike`](../user-guide/skills/bundled/software-development/software-development-spike.md) | Throwaway experiments to validate an idea before build. | `software-development/spike` |diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.mdindex 93604424f0a..315ecf7fefd 100644--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md@@ -21,7 +21,7 @@ Delegate coding to Claude Code CLI (features, PRs).| License | MIT || Platforms | linux, macos, windows || Tags | `Coding-Agent`, `Claude`, `Anthropic`, `Code-Review`, `Refactoring`, `PTY`, `Automation` |-| Related skills | [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`opencode`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md) |+| Related skills | [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md), [`opencode`](../../optional/autonomous-ai-agents/autonomous-ai-agents-opencode.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.mdindex 4d91b3f034f..9e1a056cab6 100644--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md@@ -21,7 +21,7 @@ Use, configure, theme, extend, and orchestrate Hermes Agent.| License | MIT || Platforms | linux, macos, windows || Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |-| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`opencode`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md) |+| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`opencode`](../../optional/autonomous-ai-agents/autonomous-ai-agents-opencode.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.mdindex 050dbf1b42a..d919921e431 100644--- a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md+++ b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md@@ -21,7 +21,7 @@ Design one-off HTML artifacts (landing, deck, prototype).| License | MIT || Platforms | linux, macos, windows || Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |-| Related skills | [`design-md`](../../bundled/creative/creative-design-md.md), [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md) |+| Related skills | [`design-md`](../../optional/creative/creative-design-md.md), [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md) |## Reference: full SKILL.md@@ -35,7 +35,7 @@ Use this skill when the user asks for design work that would normally fit ClaudeThe goal is to preserve Claude Design's useful design behavior and taste while removing hosted-tool plumbing that does not exist in normal agent environments.-**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.+**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format; an optional skill, installed with `hermes skills install official/creative/design-md`).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.## When To Use This Skill vs `popular-web-designs` vs `design-md`diff --git a/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md b/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.mdindex 81b3e487379..dacb1d45685 100644--- a/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md+++ b/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md@@ -40,8 +40,8 @@ system, shadows, responsive behavior, and practical agent prompts with exact CSSPair it with this skill when the user wants a thoughtfully-designed page styledafter a known brand: `claude-design` drives the workflow, this skill suppliesthe visual vocabulary.-- **`design-md`** — use when the deliverable is a formal DESIGN.md token spec- file, not a rendered artifact.+- **`design-md`** (optional: `hermes skills install official/creative/design-md`) —+ use when the deliverable is a formal DESIGN.md token spec file, not a rendered artifact.## How to Usediff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.mdindex bb7b6c0bfeb..7b5e5c2c6e2 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md@@ -21,7 +21,7 @@ Extract cited obligations, deadlines, tasks from documents.| License | MIT || Platforms | linux, macos, windows || Tags | `Documents`, `OCR`, `Action-Items`, `Deadlines`, `Extraction` |-| Related skills | [`pdf`](../../bundled/productivity/productivity-pdf.md), [`pdf`](../../bundled/productivity/productivity-pdf.md), [`docx`](../../bundled/productivity/productivity-docx.md), [`notion`](../../bundled/productivity/productivity-notion.md) |+| Related skills | [`pdf`](../../bundled/productivity/productivity-pdf.md), [`microsoft-office`](../../bundled/productivity/productivity-microsoft-office.md), [`notion`](../../optional/productivity/productivity-notion.md) |## Reference: full SKILL.md@@ -31,7 +31,7 @@ The following is the complete skill definition that Hermes loads when this skill# Document to Action Items-Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `pdf` / `pdf` / `docx` skills own extraction mechanics; this skill owns what happens to the extracted content.+Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `pdf` and `microsoft-office` skills own extraction mechanics; this skill owns what happens to the extracted content.## When to Usediff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.mddeleted file mode 100644index d472dc868ff..00000000000--- a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md+++ /dev/null@@ -1,251 +0,0 @@-----title: "Docx — Create, read, edit, template, and review Word .docx files"-sidebar_label: "Docx"-description: "Create, read, edit, template, and review Word .docx files"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Docx--Create, read, edit, template, and review Word .docx files.--## Skill metadata--| | |-|---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/docx` |-| Version | `1.1.0` |-| Author | Nous Research |-| License | MIT |-| Platforms | linux, macos, windows |-| Tags | `word`, `docx`, `documents`, `office`, `templates`, `revisions`, `comments` |-| Related skills | [`pdf`](../../bundled/productivity/productivity-pdf.md), [`xlsx`](../../bundled/productivity/productivity-xlsx.md), [`powerpoint`](../../bundled/productivity/productivity-powerpoint.md) |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Docx Skill--Create, read, edit, and template Microsoft Word `.docx` files with-python-docx via small CLIs. It handles text, styles, lists, tables,-images, headers/footers, `{{token}}` templating, tracked changes-(list/accept/reject), comments (list/add/delete), TOC and page-number-fields, and package health checks. It does not render documents itself-(PDF needs LibreOffice — see Converting to PDF) or edit legacy `.doc`.--## When to Use--- The user asks to generate a Word document (report, letter, contract).-- You need the text, outline, styles, or embedded images of a `.docx`.-- You must change an existing `.docx`: replace text, edit table cells,- insert/delete paragraphs, apply styles, merge fragmented runs.-- You have a `.docx` template with `{{placeholders}}` to fill from data.-- The document has tracked changes to review, accept, or reject.-- You need to read reviewers' comments, or add/delete comments.-- A `.docx` won't open or behaves oddly and you need corruption triage.-- The document needs a table of contents or "Page X of Y" footers.-- Not for: `.doc` (legacy), `.odt`, or WYSIWYG layout work.--## Prerequisites--- Python 3.10+ with `python-docx` (import name `docx`; lxml comes with it).-- Pick the interpreter with `terminal`. Use `python` when it already imports- the libraries (the Hermes Docker image ships them). Otherwise, when `hermes`- is on PATH, let Hermes build its shared, pinned documents environment under- the Hermes home: it survives container restarts, never touches the Hermes- install itself, and is safe to run from several agents at once. When it is- not (the terminal runs in a Docker sandbox, which has no Hermes), the block- builds a venv in the sandbox home with the same pinned versions. Use this- exact block in every document skill so they all share one environment:-- ```bash- python -c "import docx" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then- PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"- else- PY="$HOME/.cache/hermes-docs-venv/bin/python"- "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (- # Safe to run from several agents at once: each caller builds a private venv,- # a symlink publishes the first finished one atomically, the others delete theirs.- mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1- old="$(readlink hermes-docs-venv)" # an earlier build that no longer imports, if any- python3 -m venv "$stage" &&- "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&- "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&- if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv- elif [ "$(readlink hermes-docs-venv)" = "$old" ]; then- ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&- case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac- fi 2>/dev/null- [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"- )- fi- export PY- "$PY" scripts/docx_create.py --help- ```-- Run every helper below with `"$PY"`. In PowerShell (Hermes runs on that- host, so it is on PATH):- `$env:PY = hermes pm environment documents --extra documents --extra documents-pdf`.- Never `pip install` into the interpreter that runs Hermes or into the- `hermes pm environment` one; Hermes owns both.-- Comments `add` uses the native API on python-docx >= 1.2 and an XML- fallback on older versions — both are automatic.-- For image blocks: the image files must exist locally (PNG/JPEG).--## How to Run--All helpers live in `scripts/` next to this file. Run them with the-`terminal` tool; each supports `--help` and prints JSON to stdout.--```bash-python scripts/docx_create.py spec.json out.docx-python scripts/docx_read.py out.docx --text-python scripts/docx_edit.py replace out.docx --find old --replace new-python scripts/docx_template.py tpl.docx values.json filled.docx-python scripts/docx_revisions.py list out.docx-python scripts/docx_comments.py list out.docx-python scripts/docx_validate.py out.docx-```--## Quick Reference--| Task | Command |-| --- | --- |-| Create from JSON spec | `docx_create.py spec.json out.docx` |-| Full text (body+tables+headers/footers) | `docx_read.py f.docx --text` |-| Heading outline + table shapes | `docx_read.py f.docx --structure` |-| Styles actually used | `docx_read.py f.docx --styles` |-| Extract embedded images | `docx_read.py f.docx --images outdir/` |-| Detect tracked changes/comments | `docx_read.py f.docx --revisions` |-| Find/replace (formatting kept) | `docx_edit.py replace f.docx --find A --replace B -o out.docx` |-| Set a table cell | `docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X` |-| Insert paragraph before index N | `docx_edit.py insert f.docx --index N --text X --style Normal` |-| Delete paragraph N | `docx_edit.py delete f.docx --index N` |-| Apply style to paragraph N | `docx_edit.py style f.docx --index N --style "Heading 1"` |-| Merge equal-format adjacent runs | `docx_edit.py normalize f.docx -o out.docx` |-| Insert TOC field before para N | `docx_edit.py toc f.docx --index N -o out.docx` |-| "Page X of Y" footer fields | `docx_edit.py page-numbers f.docx` |-| Fill `{{tokens}}` | `docx_template.py tpl.docx values.json out.docx --strict` |-| List revisions (id/author/date/text) | `docx_revisions.py list f.docx` |-| Accept / reject all revisions | `docx_revisions.py accept-all f.docx -o out.docx` (or `reject-all`) |-| Accept / reject one revision | `docx_revisions.py accept f.docx --id 3 -o out.docx` |-| List comments (+anchored text) | `docx_comments.py list f.docx` |-| Add comment anchored to text | `docx_comments.py add f.docx --target "phrase" --text "note" --author You` |-| Delete comment by id | `docx_comments.py delete f.docx --id 0` |-| Health-check the package | `docx_validate.py f.docx` (exit 1 on errors) |--## Procedure--1. **Create.** Write a JSON spec with `write_file`, then run- `scripts/docx_create.py`. The spec supports: `page` (size + margins in- mm), `header`/`footer` strings, `footer_page_numbers` (adds a- "Page X of Y" field footer), `styles` (custom paragraph styles with- font, size, bold/italic, hex `color`), and `blocks` — `heading`- (level 1-9), `paragraph` (either `text` or a `runs` list where each run- may set `bold`/`italic`/`underline`), `bullet_list`, `numbered_list`,- `table` (`header` row rendered bold, `rows`, optional built-in table- `style` such as `Table Grid`), `image` (`path`, optional `width_mm`),- `toc` (Table of Contents field), and `page_break`. The full spec- format is documented at the top of `scripts/docx_create.py`.-2. **Read.** Use `scripts/docx_read.py` with exactly one mode flag.- `--text` returns body paragraphs, all table cell text, and- header/footer text as JSON. `--structure` returns the heading outline- plus paragraph/table/section counts. `--images DIR` copies every file- under `word/media/` out of the package.-3. **Edit.** Use `scripts/docx_edit.py`. `replace` walks body, tables- (nested included), headers and footers, and preserves run formatting;- add `--body-only` to skip headers/footers. Pass `-o out.docx` to keep- the original; omit it to edit in place. Paragraph indices for- `insert`/`delete`/`style`/`toc` refer to `--structure`/`--text` body- order. Run `normalize` first on documents that came out of heavy Word- editing — it merges adjacent runs with identical formatting so later- find-replace matches reliably.-4. **Review revisions.** `docx_revisions.py list` reports every `w:ins`- and `w:del` (id, author, date, affected text) anywhere in body,- tables, headers, or footers. `accept-all` / `reject-all` resolve them- in bulk; `accept`/`reject --id N` handles a single revision. Accept- keeps insertions and drops deleted text; reject does the reverse.-5. **Comments.** `docx_comments.py list` returns each comment's id,- author, date, body text, and the document text it is anchored to.- `add --target "some phrase"` anchors a new comment to the first- occurrence of that phrase (runs are split as needed; formatting is- preserved). `delete --id N` removes the comment and its markers- without touching document text.-6. **Template.** Put `{{name}}`-style tokens in the document. Run- `scripts/docx_template.py` with a JSON object of values. Use- `--strict` to fail when tokens remain unfilled; the JSON output lists- `filled` counts and `unfilled_tokens` either way.-7. **Verify** (always): re-read the output with `--text` or- `--structure`, and run `docx_validate.py` on anything you produced- via revision/comment surgery.--## Converting to PDF--No script needed. When LibreOffice is installed, convert headlessly:--```bash-soffice --headless --convert-to pdf --outdir outdir/ file.docx-```--Check availability first (`command -v soffice || command -v-libreoffice`). If neither exists, tell the user PDF conversion is-unavailable in this environment rather than improvising — python-docx-cannot render PDFs, and layout fidelity requires a real renderer.--## Pitfalls--- **Tokens split across runs.** Word often fragments text into several- runs. The replace helpers collapse matched runs (replacement inherits- the first run's formatting); running `docx_edit.py normalize` first- reduces fragmentation for all later edits.-- **Revision coverage.** `docx_revisions.py` resolves run-level- insertions and deletions (the overwhelming majority). Paragraph-mark- and table-row revisions, format-change records, and moves are detected- by `--revisions` but not auto-resolved — see- `references/revisions-and-comments.md` and hand those to Word.-- **Comment threading.** Replies and "resolved" status live in- `commentsExtended.xml`, which this skill ignores; comments it adds are- plain top-level comments.-- **Field results are computed by Word.** `toc`, `page-numbers`, and the- `toc`/`footer_page_numbers` spec options write *field codes*.- Word/LibreOffice populates the actual entries and numbers when the- file is opened (Word may prompt to update fields); python-docx never- computes them, so placeholder text shows until then.-- **Validation is a health check, not schema validation.**- `docx_validate.py` verifies the zip, required parts, relationship- targets, image magic bytes, and referenced styles. It is NOT XSD- validation — a file can pass and still contain XML Word dislikes.-- **Style names must exist.** Applying a style that isn't defined in the- document raises `KeyError`. Built-ins like `Heading 1`, `List Bullet`,- `List Number`, `Table Grid` exist in the default template; custom- styles must be declared in the create spec first.-- **Numbered lists restart.** `List Number` relies on Word's default- numbering; separate lists in one document may continue numbering- instead of restarting. Warn users needing precise multi-list numbering.-- **Cell writes replace formatting.** `set-cell` uses `cell.text = ...`,- which resets runs in that cell to plain formatting.-- **Encoding.** All JSON specs/values files are read as UTF-8 explicitly;- never rely on locale defaults when writing your own glue code.-- **Don't unzip-and-sed the XML.** Edit through the scripts (or- python-docx); raw text substitution in `document.xml` corrupts files- easily. Use `patch`/`write_file` only for the JSON inputs, never on the- `.docx` itself.--## Verification--- After create/edit/template, run `docx_read.py out.docx --text` and- check the expected strings appear (and old strings are gone).-- After accept/reject, `docx_revisions.py list` should return `[]` (or- only the ids you intentionally left); after comment surgery,- `docx_comments.py list` should reflect the change and `--text` output- must be unchanged.-- `docx_validate.py out.docx` exits 0 with `"ok": true` on a healthy- package — run it after any revision/comment/field manipulation.-- For templates run with `--strict`, or check `unfilled_tokens == []`.-- Structure checks: `--structure` should show the expected heading- outline and table shapes; `--styles` confirms custom styles applied.diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.mdindex e25810984ea..4bc39457a88 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md@@ -21,7 +21,7 @@ Turn meeting notes into cited decisions, owners, tickets.| License | MIT || Platforms | linux, macos, windows || Tags | `Meetings`, `Action-Items`, `Follow-Up`, `Productivity` |-| Related skills | [`teams-meeting-pipeline`](../../bundled/productivity/productivity-teams-meeting-pipeline.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`notion`](../../bundled/productivity/productivity-notion.md) |+| Related skills | [`teams-meeting-pipeline`](../../bundled/productivity/productivity-teams-meeting-pipeline.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`notion`](../../optional/productivity/productivity-notion.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-microsoft-office.md b/website/docs/user-guide/skills/bundled/productivity/productivity-microsoft-office.mdnew file mode 100644index 00000000000..b9a6dd6cdf3--- /dev/null+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-microsoft-office.md@@ -0,0 +1,178 @@+---+title: "Microsoft Office — Create, read, and edit Word, PowerPoint, and Excel files"+sidebar_label: "Microsoft Office"+description: "Create, read, and edit Word, PowerPoint, and Excel files"+---++{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}++# Microsoft Office++Create, read, and edit Word, PowerPoint, and Excel files.++## Skill metadata++| | |+|---|---|+| Source | Bundled (installed by default) |+| Path | `skills/productivity/microsoft-office` |+| Version | `2.0.0` |+| Author | Nous Research |+| License | MIT |+| Platforms | linux, macos, windows |+| Tags | `office`, `word`, `docx`, `powerpoint`, `pptx`, `excel`, `xlsx`, `csv`, `documents`, `slides`, `spreadsheets` |+| Related skills | [`pdf`](../../bundled/productivity/productivity-pdf.md) |++## Reference: full SKILL.md++:::info+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.+:::++# Microsoft Office Skill++Create, read, edit, and template Word (`.docx`), PowerPoint (`.pptx`), and+Excel (`.xlsx`, `.csv`) files offline with small Python CLIs built on+python-docx, python-pptx, and openpyxl. Office itself is never needed. It does+not open legacy binary formats (`.doc`, `.ppt`, `.xls`) and does not render+pages without LibreOffice.++## When to Use++Pick the format, then read its reference with `skill_view` before working:++| File | Reference | Typical asks |+| --- | --- | --- |+| `.docx` | `references/word.md` | reports, letters, contracts, `{{token}}` templates, tracked changes, comments |+| `.pptx` | `references/powerpoint.md` | pitch decks, brand-template decks, chart refreshes, speaker notes, slide PNGs |+| `.xlsx`, `.csv` | `references/excel.md` | styled multi-sheet workbooks, formulas, charts, CSV conversion, row/column restructures |++Deeper notes: `references/revisions-and-comments.md` (Word review markup) and+`references/restructuring.md` (Excel reference shifting).++- Not for `.doc`/`.ppt`/`.xls`: convert first with+ `soffice --headless --convert-to docx|pptx|xlsx old-file` when LibreOffice is installed.+- Not for `.odt`/`.odp`/`.ods`, or WYSIWYG layout work.++## Prerequisites++- Python 3.10+ with `python-docx`, `python-pptx`, and `openpyxl` (import names+ `docx`, `pptx`, `openpyxl`).+- Pick the interpreter with `terminal`. Use `python` when it already imports+ the libraries (the Hermes Docker image ships them). Otherwise, when `hermes`+ is on PATH, let Hermes build its shared, pinned documents environment under+ the Hermes home: it survives container restarts, never touches the Hermes+ install itself, and is safe to run from several agents at once. When it is+ not (the terminal runs in a Docker sandbox, which has no Hermes), the block+ builds a venv in the sandbox home with the same pinned versions. Use this+ exact block in every document skill so they all share one environment:++ ```bash+ python -c "import docx, pptx, openpyxl" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then+ PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"+ else+ PY="$HOME/.cache/hermes-docs-venv/bin/python"+ "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (+ # Safe to run from several agents at once: each caller builds a private venv,+ # a symlink publishes the first finished one atomically, the others delete theirs.+ mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1+ old="$(readlink hermes-docs-venv)" # an earlier build that no longer imports, if any+ python3 -m venv "$stage" &&+ "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&+ "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&+ if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv+ elif [ "$(readlink hermes-docs-venv)" = "$old" ]; then+ ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&+ case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac+ fi 2>/dev/null+ [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"+ )+ fi+ export PY+ "$PY" scripts/docx_create.py --help+ ```++ Run every helper with `"$PY"`. In PowerShell (Hermes runs on that host, so+ it is on PATH):+ `$env:PY = hermes pm environment documents --extra documents --extra documents-pdf`.+ Never `pip install` into the interpreter that runs Hermes or into the+ `hermes pm environment` one; Hermes owns both.+- Optional: LibreOffice (`soffice`) for PDF export, Excel recalculation, and+ slide rendering, plus poppler (`pdftoppm` or `pdftocairo`) for slide PNGs.+ The helpers that need them report what is missing and exit 0.++## How to Run++Every helper lives in `scripts/`, is an argparse CLI with `--help`, prints+JSON to stdout, and exits non-zero on failure. Run them with `terminal` from+the skill directory. Author JSON specs with `write_file`; read results with+`read_file` or straight from stdout.++```bash+"$PY" scripts/docx_create.py spec.json out.docx+"$PY" scripts/pptx_create.py deck.json out.pptx+"$PY" scripts/xlsx_create.py spec.json report.xlsx+```++## Quick Reference++| Task | Word | PowerPoint | Excel |+| --- | --- | --- | --- |+| Create from JSON spec | `docx_create.py` | `pptx_create.py` | `xlsx_create.py`, `csv_to_xlsx.py` |+| Read back | `docx_read.py --text/--structure` | `pptx_read.py --outline` | `xlsx_read.py --sheets/--json` |+| Edit | `docx_edit.py` | `pptx_edit.py` | `xlsx_edit.py`, `xlsx_restructure.py` |+| Fill a template | `docx_template.py` | `pptx_from_template.py` | — |+| Review / check | `docx_revisions.py`, `docx_comments.py`, `docx_validate.py` | `pptx_render.py` (slide PNGs) | `xlsx_recalc.py`, `xlsx_to_csv.py` |++The per-format reference has the full flag table.++## Procedure++1. Identify the format from the file extension or the ask, and load its+ reference (`skill_view` with `file_path=references/<format>.md`).+2. Set `PY` with the Prerequisites block once per session.+3. Create, edit, or read with that format's helpers; pass an output path to+ keep the original whenever the helper supports one.+4. Verify the result as the reference's Verification section says, then give+ the user the exact output path.++## Converting to PDF++When LibreOffice is installed, convert headlessly:++```bash+soffice --headless --convert-to pdf --outdir out/ file.docx # also .pptx, .xlsx+soffice --headless --convert-to csv --outdir out/ report.xlsx # first sheet only+```++Check first with `command -v soffice || command -v libreoffice`. Fonts not on+the host are substituted, so render-check decks before shipping. There is no+pure-Python path to PDF for any of these formats: if `soffice` is missing, say+so rather than approximating. For other sheets use+`xlsx_to_csv.py --sheet NAME`.++## Pitfalls++- **Never unzip-and-edit the XML.** These files are zip packages; raw text+ substitution corrupts them. Edit through the helpers (or the libraries) and+ use `patch`/`write_file` only for JSON inputs.+- **Text is split into runs.** Word and PowerPoint fragment text at edit+ boundaries; the replace helpers merge equal-format runs first, but a match+ across differently formatted runs takes the first run's formatting.+- **Nothing computes fields or formulas.** Word TOC/page fields and Excel+ formulas are filled in by the office app on open (or by `xlsx_recalc.py`).+- **Encoding.** Write specs as UTF-8; the helpers read UTF-8 explicitly.+- Format-specific traps are in each reference.++## Verification++- Re-read every output with the format's read helper and check the expected+ content is there and the old content is gone.+- Word: `docx_validate.py out.docx` exits 0 after revision, comment, or field+ surgery.+- PowerPoint: render with `pptx_render.py` and check each PNG with+ `vision_analyze` when the render tools exist.+- Excel: `xlsx_read.py --formulas` lists written formulas; run+ `xlsx_recalc.py` when cached values matter.+- The bundled tests are the full contract:+ `"$PY" -m pytest tests/ -q` (needs pytest in that interpreter).diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.mdindex 6211679539e..330f50718f9 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md@@ -21,7 +21,7 @@ PDF files: create, read, merge, fill, OCR, edit text.| License | MIT || Platforms | linux, macos, windows || Tags | `pdf`, `documents`, `forms`, `ocr`, `text-extraction`, `reportlab`, `pypdf`, `pdfplumber`, `pymupdf`, `marker` |-| Related skills | [`docx`](../../bundled/productivity/productivity-docx.md), [`xlsx`](../../bundled/productivity/productivity-xlsx.md), [`powerpoint`](../../bundled/productivity/productivity-powerpoint.md) |+| Related skills | [`microsoft-office`](../../bundled/productivity/productivity-microsoft-office.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.mddeleted file mode 100644index 039533945e3..00000000000--- a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md+++ /dev/null@@ -1,275 +0,0 @@-----title: "Powerpoint — Create, read, edit .pptx decks with python-pptx"-sidebar_label: "Powerpoint"-description: "Create, read, edit .pptx decks with python-pptx"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Powerpoint--Create, read, edit .pptx decks with python-pptx.--## Skill metadata--| | |-|---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/powerpoint` |-| Version | `1.1.0` |-| Author | Nous Research |-| License | MIT |-| Platforms | linux, macos, windows |-| Tags | `pptx`, `powerpoint`, `presentations`, `slides`, `office`, `python-pptx` |-| Related skills | [`docx`](../../bundled/productivity/productivity-docx.md), [`xlsx`](../../bundled/productivity/productivity-xlsx.md), [`pdf`](../../bundled/productivity/productivity-pdf.md) |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Powerpoint Skill--Create, inspect, and edit PowerPoint (.pptx) presentations using the-python-pptx library. Five helper scripts cover deck creation from a JSON-spec, structured read-back, in-place edits, template-driven brand decks,-and slide rendering — all offline, no PowerPoint installation required.--## When to Use--- The user asks to build a slide deck, report presentation, or pitch deck.-- You need to extract text, notes, tables, chart data, or images from a- .pptx someone shared.-- You need to update an existing deck: replace text, refresh or patch- chart data, swap a logo, duplicate/remove/reorder slides, set- backgrounds, footers, hyperlinks, or speaker notes.-- You must produce an on-brand deck from a company .pptx template.-- Do NOT use this for .ppt (legacy binary) files — convert them first with- `soffice --convert-to pptx old.ppt` if LibreOffice is available.--## Prerequisites--- Python 3.10+ with `python-pptx` (import name `pptx`).-- Pick the interpreter with `terminal`. Use `python` when it already imports- the libraries (the Hermes Docker image ships them). Otherwise, when `hermes`- is on PATH, let Hermes build its shared, pinned documents environment under- the Hermes home: it survives container restarts, never touches the Hermes- install itself, and is safe to run from several agents at once. When it is- not (the terminal runs in a Docker sandbox, which has no Hermes), the block- builds a venv in the sandbox home with the same pinned versions. Use this- exact block in every document skill so they all share one environment:-- ```bash- python -c "import pptx" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then- PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"- else- PY="$HOME/.cache/hermes-docs-venv/bin/python"- "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (- # Safe to run from several agents at once: each caller builds a private venv,- # a symlink publishes the first finished one atomically, the others delete theirs.- mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1- old="$(readlink hermes-docs-venv)" # an earlier build that no longer imports, if any- python3 -m venv "$stage" &&- "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&- "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&- if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv- elif [ "$(readlink hermes-docs-venv)" = "$old" ]; then- ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&- case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac- fi 2>/dev/null- [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"- )- fi- export PY- "$PY" scripts/pptx_create.py --help- ```-- Run every helper below with `"$PY"`. In PowerShell (Hermes runs on that- host, so it is on PATH):- `$env:PY = hermes pm environment documents --extra documents --extra documents-pdf`.- Never `pip install` into the interpreter that runs Hermes or into the- `hermes pm environment` one; Hermes owns both.-- Optional: LibreOffice (`soffice`) plus poppler (`pdftoppm` or- `pdftocairo`) for rendering slides to PNGs and for PDF export.- `pptx_render.py` detects both with `shutil.which` and degrades- gracefully (reports `{"rendered": false, "missing": [...]}`, exit 0)- when absent — all create/read/edit operations work without them.-- Check availability via `terminal`:- `"$PY" -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`.--## How to Run--All scripts live in `scripts/`, take `--help`, print JSON to stdout, and-exit non-zero on failure. Run them with `terminal`:--```bash-python scripts/pptx_create.py deck.json out.pptx-python scripts/pptx_read.py deck.pptx --outline # full JSON outline-python scripts/pptx_read.py deck.pptx --notes # speaker notes-python scripts/pptx_read.py deck.pptx --images ./img # export pictures-python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp"-python scripts/pptx_edit.py deck.pptx --chart-data update.json-python scripts/pptx_edit.py deck.pptx --duplicate-slide 2-python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0-python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json-python scripts/pptx_render.py deck.pptx --outdir ./render # slide PNGs-```--Author JSON specs with `write_file`; inspect script output and generated-JSON with `read_file`.--## Quick Reference--| Task | Command |-|---|---|-| New deck from spec | `pptx_create.py spec.json out.pptx` |-| 16:9 vs 4:3 | `"slide_size": "16:9"` or `"4:3"` in the spec |-| Outline as JSON | `pptx_read.py deck.pptx --outline` |-| Export images | `pptx_read.py deck.pptx --images DIR` |-| Replace text | `pptx_edit.py deck.pptx --replace-text OLD NEW` |-| Replace chart data | `pptx_edit.py deck.pptx --chart-data spec.json` |-| Patch one series | same flag, spec with `"ops"` (see below) |-| Swap picture | `pptx_edit.py deck.pptx --swap-image N NAME new.png` |-| Duplicate slide | `pptx_edit.py deck.pptx --duplicate-slide N` |-| Remove slide | `pptx_edit.py deck.pptx --remove-slide N` |-| Reorder slide | `pptx_edit.py deck.pptx --move-slide FROM TO` |-| Slide background | `pptx_edit.py deck.pptx --set-background N RRGGBB` |-| Hyperlink runs | `pptx_edit.py deck.pptx --hyperlink N TEXT URL` |-| Slide number on | `pptx_edit.py deck.pptx --enable-slide-number N` |-| Footer text | `pptx_edit.py deck.pptx --set-footer N TEXT` |-| Set notes | `pptx_edit.py deck.pptx --set-notes N TEXT` |-| Append notes | `pptx_edit.py deck.pptx --append-notes N TEXT` |-| Fill template | `pptx_from_template.py tpl.pptx out.pptx --values v.json` |-| Render slide PNGs | `pptx_render.py deck.pptx --outdir DIR` |--## Procedure--### 1. Create a deck--Write a JSON spec (see `pptx_create.py --help` for the full format), then-run `pptx_create.py`. Per slide you can set: `layout` (title,-title_content, section, two_content, title_only, blank), `title`,-`subtitle`, `bullets` (strings, or dicts with `level` 0-4, `size` pt,-`bold`, `italic`, `font`, `color` hex, `link` URL for a hyperlink),-`background` (solid hex), `footer` (text; enables the layout's footer-placeholder), `slide_number` (true; enables the layout's slide-number-placeholder), `images` (path + left/top/width/height in inches), `tables`-(`rows` as list-of-lists), `shapes` (rectangle, rounded_rectangle, oval,-diamond, right_arrow, chevron, with `fill` hex + optional `text`),-`charts` (bar, bar_h, line, pie with `categories` + `series`), and-`notes` (speaker notes).--### 2. Read a deck--`pptx_read.py deck.pptx --outline` returns slide size, layout inventory,-and per slide: layout name, all shape texts, table cells, image inventory-(filename/ext/bytes), chart categories/series/values, and speaker notes.-Use `--images DIR` to dump embedded pictures to files, then-`vision_analyze` on any exported image if you need to see its content.--### 3. Edit a deck--`pptx_edit.py` combines operations in one pass; use `--output` to keep the-original. Text replacement scans slide shapes, table cells, and notes.-Image swap retargets the picture's relationship id so position and size-are preserved. Slide removal drops the relationship and the `<p:sldId>`-entry; reorder moves the `<p:sldId>` element within `<p:sldIdLst>`-(python-pptx has no public API for either — the script does the XML-level-work). `--duplicate-slide N` appends an independent deep copy of slide N:-shape XML plus image/media/hyperlink relationships are cloned and rIds-remapped, so editing the copy never touches the original. Chart slides-are refused (see Pitfalls). `--set-notes`/`--append-notes` edit speaker-notes; `--set-background`, `--hyperlink`, `--enable-slide-number`, and-`--set-footer` handle deck polish.--Chart updates take a JSON spec via `--chart-data`. Full replace:-`{"slide": 0, "chart": 0, "categories": [...], "series": {...}}`. For-surgical edits, pass `"ops"` instead — a list of-`{"op": "update_series", "name": ..., "values": [...]}`,-`add_series`, `remove_series`, `rename_category` (`from`/`to` or-`index`), and `set_title`. python-pptx can only swap a chart's entire-dataset (`replace_data`), so ops are implemented as read-existing →-modify → replace; the per-part UX is a wrapper, and any chart data not-expressible as categories + numeric series will be normalized by the-round-trip.--### 4. Build from a template--`pptx_from_template.py` opens a brand .pptx, replaces every-`{{token}}` from a values JSON across slides/tables/notes, and can append-new slides that use the template's own layouts (by layout name or index)-so they inherit the master's fonts and colors. Tip: to start from a-template with zero slides, delete existing ones afterward with-`pptx_edit.py --remove-slide`.--### 5. Visual verification--`pptx_render.py deck.pptx --outdir ./render` converts the deck to PDF-with `soffice --headless` and splits it into one PNG per slide with-`pdftoppm` (or `pdftocairo`). Output JSON lists the PNG paths — review-each with `vision_analyze`. When either tool is missing the script exits-0 with `{"rendered": false, "missing": [...]}` and guidance; fall back to-the JSON outline from `pptx_read.py`, which verifies content and-structure, just not visuals.--## Converting to PDF--If LibreOffice is installed, export the finished deck to PDF directly:--```bash-soffice --headless --convert-to pdf --outdir ./out deck.pptx-```--The output lands at `./out/deck.pdf`. Fonts not installed on the host are-substituted, so render-verify (Procedure step 5) before shipping the PDF.-There is no offline pure-Python .pptx→PDF path; if `soffice` is absent,-say so rather than approximating.--## Pitfalls--- **Run splitting**: PowerPoint fragments paragraph text into runs at- spell-check and edit boundaries. `--replace-text` first merges adjacent- runs whose formatting is identical, so matches split across such runs- are replaced with formatting fully preserved. Only when a match spans- *genuinely differently-formatted* runs is the paragraph rewritten with- the first run's formatting — verify those slides after replacement.-- **Chart slides cannot be duplicated**: each chart relationship embeds a- separate XLSX workbook part; cloning that graph reliably is not- supported, so `--duplicate-slide` refuses chart slides cleanly instead- of corrupting the deck. Rebuild the chart on a new slide instead.- External-hyperlink and image/media rels are carried over; layout and- notes rels are recreated fresh.-- **Chart ops are a wrapper**: python-pptx replaces the whole dataset;- `"ops"` round-trips existing plot data through `replace_data`, and- changing chart *type* is not possible.-- **Reordering is XML-level**: python-pptx has no supported reorder API.- `--move-slide` manipulates `<p:sldIdLst>` directly; safe for ordinary- decks but re-read the deck afterward to confirm.-- **Copying slides between decks is unsupported** — duplication works- only within one deck, where layouts and masters are shared.-- Footer/slide-number enablement copies the placeholder from the slide's- layout; on layouts without those placeholders, `--set-footer` fails- with a clear message (add a textbox instead).-- Hyperlinks apply to whole runs; `--hyperlink` links every run- containing the given text on that slide.-- The default python-pptx template is 4:3; the create script sets 16:9- unless the spec says otherwise. Custom templates keep their own size.-- Layout indexes vary by template. For brand templates, list layout names- first: `pptx_read.py template.pptx --outline` (`layouts_available`).-- `slide.shapes.title` is None on blank layouts — the create script- handles this, but remember it when writing ad-hoc python-pptx code.-- Always pass `encoding="utf-8"` when writing spec files; tokens like- `{{city}}` may be filled with non-ASCII values.--## Verification--1. After any create/edit, run `pptx_read.py OUT.pptx --outline` and check- slide count, texts, tables, notes, and chart values match intent.-2. `--images DIR` then file-size check confirms pictures embedded.-3. Render every slide with `pptx_render.py deck.pptx --outdir ./render`- and review each PNG with `vision_analyze` — this catches overlapping- shapes, truncated text, and color problems the outline cannot. If the- render tools are missing, the script says so; rely on the outline.-4. The bundled test suite is the full contract:- `python -m pytest tests/ -q` (requires python-pptx + pytest).diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.mdindex 0e13a1b3b63..d9019437b1f 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md@@ -21,7 +21,7 @@ Weekly reset: commitments, stalled work, next-week plan.| License | MIT || Platforms | linux, macos, windows || Tags | `Weekly-Review`, `Planning`, `Tasks`, `Calendar`, `Productivity` |-| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`notion`](../../bundled/productivity/productivity-notion.md), [`airtable`](../../bundled/productivity/productivity-airtable.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`email-inbox-triage`](../../bundled/email/email-email-inbox-triage.md) |+| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`notion`](../../optional/productivity/productivity-notion.md), [`airtable`](../../optional/productivity/productivity-airtable.md), [`google-workspace`](../../bundled/productivity/productivity-google-workspace.md), [`email-inbox-triage`](../../bundled/email/email-email-inbox-triage.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.mddeleted file mode 100644index 8aa3e300605..00000000000--- a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md+++ /dev/null@@ -1,252 +0,0 @@-----title: "Xlsx — Create, read, edit Excel .xlsx workbooks and CSVs"-sidebar_label: "Xlsx"-description: "Create, read, edit Excel .xlsx workbooks and CSVs"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Xlsx--Create, read, edit Excel .xlsx workbooks and CSVs.--## Skill metadata--| | |-|---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/xlsx` |-| Version | `1.1.0` |-| Author | Nous Research |-| License | MIT |-| Platforms | linux, macos, windows |-| Tags | `excel`, `spreadsheet`, `xlsx`, `csv`, `openpyxl`, `productivity` |-| Related skills | [`docx`](../../bundled/productivity/productivity-docx.md), [`pdf`](../../bundled/productivity/productivity-pdf.md), [`powerpoint`](../../bundled/productivity/productivity-powerpoint.md) |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Xlsx Skill--Work with Excel .xlsx workbooks using Python and openpyxl: build styled-multi-sheet workbooks with formulas and charts, inspect or dump existing-files, edit cells and structure, and convert to/from CSV. All helper-scripts are argparse CLIs that print JSON and use explicit UTF-8 I/O.--## When to Use--- Creating .xlsx reports: multiple sheets, number formats, styling,- merged cells, freeze panes, autofilter, conditional formatting,- charts, data-validation dropdowns, native Excel tables, defined- names, hyperlinks, cell notes, sheet protection.-- Reading a workbook: sheet inventory, dumping data as JSON or CSV,- listing formulas vs cached values, notes, defined names, tables.-- Editing existing files: set cells, append rows, insert/delete- rows/columns (reference-aware via `xlsx_restructure.py`),- copy/rename sheets, tables, names, notes, protection.-- Recalculating formulas headlessly via LibreOffice- (`xlsx_recalc.py`).-- CSV interop with type inference and non-UTF-8 encodings.-- Not for the legacy .xls binary format (use LibreOffice to convert- first: `soffice --headless --convert-to xlsx old.xls`).--## Prerequisites--- Python 3.10+ with `openpyxl`. No other third-party packages are- needed; everything else is stdlib.-- Pick the interpreter with `terminal`. Use `python` when it already imports- the libraries (the Hermes Docker image ships them). Otherwise, when `hermes`- is on PATH, let Hermes build its shared, pinned documents environment under- the Hermes home: it survives container restarts, never touches the Hermes- install itself, and is safe to run from several agents at once. When it is- not (the terminal runs in a Docker sandbox, which has no Hermes), the block- builds a venv in the sandbox home with the same pinned versions. Use this- exact block in every document skill so they all share one environment:-- ```bash- python -c "import openpyxl" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then- PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"- else- PY="$HOME/.cache/hermes-docs-venv/bin/python"- "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (- # Safe to run from several agents at once: each caller builds a private venv,- # a symlink publishes the first finished one atomically, the others delete theirs.- mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1- old="$(readlink hermes-docs-venv)" # an earlier build that no longer imports, if any- python3 -m venv "$stage" &&- "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&- "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&- if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv- elif [ "$(readlink hermes-docs-venv)" = "$old" ]; then- ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&- case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac- fi 2>/dev/null- [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"- )- fi- export PY- "$PY" scripts/xlsx_create.py --help- ```-- Run every helper below with `"$PY"`. In PowerShell (Hermes runs on that- host, so it is on PATH):- `$env:PY = hermes pm environment documents --extra documents --extra documents-pdf`.- Never `pip install` into the interpreter that runs Hermes or into the- `hermes pm environment` one; Hermes owns both.-- Optional: LibreOffice (`soffice`) for headless recalculation or- format conversion.--## How to Run--Run the helper scripts with the `terminal` tool from this skill's-`scripts/` directory (every script supports `--help`):--```bash-python scripts/xlsx_create.py spec.json report.xlsx # build from JSON spec-python scripts/xlsx_read.py report.xlsx --sheets # inventory-python scripts/xlsx_read.py report.xlsx --json --sheet Data-python scripts/xlsx_read.py report.xlsx --formulas-python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc-python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2-python scripts/xlsx_recalc.py report.xlsx-python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8-python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data-```--Author the JSON spec with `write_file`, inspect script JSON output with-`read_file` or directly from stdout.--## Quick Reference--| Task | Command |-|---|---|-| Create workbook from spec | `xlsx_create.py spec.json out.xlsx` |-| Sheet names + dimensions | `xlsx_read.py f.xlsx --sheets` |-| Dump sheet as JSON | `xlsx_read.py f.xlsx --json --sheet S` |-| Dump sheet as CSV | `xlsx_read.py f.xlsx --csv --out d.csv` |-| List formulas + cached values | `xlsx_read.py f.xlsx --formulas` |-| Set a cell / formula | `xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"` |-| Append a row | `xlsx_edit.py f.xlsx --append '[1,"x",true]'` |-| Insert 2 rows, refs NOT shifted | `xlsx_edit.py f.xlsx --insert-rows 3:2` |-| Insert 2 rows, refs shifted | `xlsx_restructure.py f.xlsx --insert-rows 3:2` |-| Delete a column, refs shifted | `xlsx_restructure.py f.xlsx --delete-cols B` |-| Create a native table | `xlsx_edit.py f.xlsx --add-table Sales:A1:C9` |-| Append inside a table | `--table-append 'Sales=["West",5]'` |-| List tables | `xlsx_edit.py f.xlsx --list-tables` |-| Defined names | `--define-name "Rates='Data'!$B$2:$B$9"` / `--delete-name Rates` / `xlsx_read.py f.xlsx --names` |-| Hyperlink | `--hyperlink "A1=https://example.com|Docs"` |-| Cell note | `--note "B2=Check this|Reviewer"`; read via `xlsx_read.py f.xlsx --notes` |-| Protect sheet (see Pitfalls) | `--protect your-password --unlock B2:B9` |-| Recalculate via LibreOffice | `xlsx_recalc.py f.xlsx` |-| Copy / rename sheet | `--copy-sheet Src:New --rename-sheet Old:New` |-| Force recalc on open | `xlsx_edit.py f.xlsx --recalc` |-| CSV -> styled xlsx | `csv_to_xlsx.py in.csv out.xlsx` |-| xlsx -> CSV | `xlsx_to_csv.py f.xlsx out.csv --encoding utf-8` |--## Procedure--1. **Create**: write a JSON spec (schema documented in- `xlsx_create.py --help` and its docstring). Each sheet supports- `rows` (scalars or styled cell objects), sparse `cells` overrides,- `column_widths`, `row_heights`, `merges`, `freeze_panes`,- `autofilter`, `conditional_formats` (cell_is rules and color- scales), `charts` (bar/line/pie from cell ranges),- `validations` (list dropdowns), `tables` (native Excel tables with- a style name), and `protection`. Workbook-level `defined_names`- maps names to refs. Cell objects also take `hyperlink` and `note`.- Typed values: JSON numbers/bools- pass through; dates use `{"value": "2026-01-31", "type": "date"}`.- Number formats are Excel format strings: currency `"$#,##0.00"`,- percent `"0.0%"`, date `"yyyy-mm-dd"`.-2. **Formulas**: set with `"formula": "SUM(B2:B9)"` in the spec or- `--set "C1==SUM(A:A)"` in the editor. When writing formulas, add- `"full_calc_on_load": true` (spec) or `--recalc` (editor); this sets- the workbook's `fullCalcOnLoad` flag so Excel/LibreOffice recompute- everything on open. openpyxl itself NEVER evaluates formulas.-3. **Read**: `--sheets` for inventory (names, dimensions, merged- ranges, chart count, tables, protection, defined names),- `--json`/`--csv` for data, `--formulas` to- pair each formula string with its cached result, `--notes` for- cell comments, `--names` for defined names. Cached results- exist only if the file was last saved by a real spreadsheet app;- files fresh from openpyxl return `null` there. To materialize- results headlessly run `xlsx_recalc.py file.xlsx` (uses- LibreOffice; prints `{"recalculated": false, ...}` and exits 0- when `soffice` is absent), then reload with `--data-only`.-4. **Edit**: `xlsx_edit.py` applies renames/copies first, then- structural row/column changes, then `--set`/`--append`. It edits in- place unless `--out` is given — copy the file first if you need the- original.-5. **Restructure**: for insert/delete on sheets that have formulas,- merges, tables, or filters, use `xlsx_restructure.py` instead of- `xlsx_edit.py`. It rewrites formula references on ALL sheets- (absolute `$` refs, ranges, cross-sheet refs), shifts merges,- autofilter, freeze panes, validation and conditional-format- ranges, table refs, defined names, and row/column dimensions, then- prints a JSON report including a `not_shifted` list. Rules and- limits: `references/restructuring.md`.-6. **CSV interop**: `csv_to_xlsx.py` infers int/float/bool/ISO-date- per cell and styles the header row; `xlsx_to_csv.py` writes ISO- dates and blank strings for empty cells. Both default to UTF-8 and- accept `--encoding` (e.g. `utf-8-sig` for Excel-friendly BOM,- `cp1252` for legacy Windows exports).--## Converting to PDF--LibreOffice converts headlessly (also works for CSV export of a single-sheet):--```bash-soffice --headless --convert-to pdf report.xlsx --outdir out/-soffice --headless --convert-to csv report.xlsx --outdir out/ # 1st sheet only-```--Only the first sheet lands in a CSV; for other sheets use-`xlsx_to_csv.py --sheet NAME`. If `soffice` is missing, install-LibreOffice or hand the file to the user unconverted.--## Pitfalls--- **openpyxl does not calculate.** Formula results are available only- via `load_workbook(path, data_only=True)` and only when the file was- previously saved by Excel/LibreOffice. Otherwise you get `None`.-- **`xlsx_edit.py` insert/delete does not shift references** (raw- openpyxl behavior). Use `xlsx_restructure.py`, which does — but even- it cannot move chart anchors, images, or conditional-format RULE- formulas; read its JSON report's `not_shifted` list and- `references/restructuring.md`.-- **Sheet protection is NOT security.** `--protect` sets the standard- xlsx sheet-protection hash: it signals "don't edit this" to- well-behaved apps and nothing more. Anyone can strip it by editing- the zip's XML or unchecking it in LibreOffice. Never rely on it for- confidentiality or integrity; it does not encrypt anything.-- **`data_only=True` then save** silently discards all formulas- (cached values replace them). Never save a workbook loaded that way- unless that is the goal.-- **Loading strips charts/images**: openpyxl does not round-trip- charts, so editing a charted workbook and saving drops the charts.- Re-add charts after editing, or avoid re-saving charted files.-- **CSV locale traps**: always pass explicit encodings (the scripts- already do) and remember European CSVs often use `;` delimiters and- decimal commas — use `--delimiter ';'` and expect strings like- `"12,5"` to stay strings.-- **Dates are datetimes**: Excel stores dates as serial numbers;- openpyxl returns `datetime`/`date` objects. Dumps here emit ISO- strings.-- Sheet names are capped at 31 chars and reject `[ ] : * ? / \`.--## Verification--- After creating: `xlsx_read.py out.xlsx --sheets` and confirm sheet- names, dimensions, merged ranges, and chart counts match intent.-- Dump data with `--json` and compare against the source values.-- After edits: re-dump the touched range; if formulas were written,- confirm `--formulas` lists them and that `--recalc` was applied.-- After `xlsx_restructure.py`: read its JSON report, then re-run- `--formulas` and `--sheets` to confirm references and ranges landed- where expected.-- For a full visual check, open in LibreOffice:- `soffice --headless --convert-to pdf out.xlsx` and inspect the PDF.diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-opencode.mdsimilarity index 98%rename from website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.mdrename to website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-opencode.mdindex c458d8d33eb..e65213a6773 100644--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-opencode.md@@ -14,8 +14,8 @@ Delegate coding to OpenCode CLI (features, PR review).| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/autonomous-ai-agents/opencode` |+| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/opencode` |+| Path | `optional-skills/autonomous-ai-agents/opencode` || Version | `1.2.0` || Author | Hermes Agent || License | MIT |diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.mdindex e05bfa83e0b..b5789d0a42a 100644--- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md+++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md@@ -21,7 +21,7 @@ Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).| License | MIT || Platforms | linux, macos || Tags | `Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM` |-| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`opencode`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |+| Related skills | [`claude-code`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md), [`codex`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md), [`opencode`](../../optional/autonomous-ai-agents/autonomous-ai-agents-opencode.md), [`hermes-agent`](../../bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.mddeleted file mode 100644index ae2b0d903a0..00000000000--- a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md+++ /dev/null@@ -1,588 +0,0 @@-----title: "Audiocraft Audio Generation — AudioCraft: MusicGen text-to-music, AudioGen text-to-sound"-sidebar_label: "Audiocraft Audio Generation"-description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Audiocraft Audio Generation--AudioCraft: MusicGen text-to-music, AudioGen text-to-sound.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/creative/audiocraft-audio-generation` |-| Path | `optional-skills/creative/audiocraft-audio-generation` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `audiocraft`, `torch>=2.0.0`, `transformers>=4.30.0` |-| Platforms | linux, macos |-| Tags | `Multimodal`, `Audio Generation`, `Text-to-Music`, `Text-to-Audio`, `MusicGen` |-| Related skills | [`heartmula`](../../optional/creative/creative-heartmula.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md) |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# AudioCraft: Audio Generation--Guide to using Meta's AudioCraft for text-to-music and text-to-audio generation with MusicGen, AudioGen, and EnCodec.--## When to use AudioCraft--**Use AudioCraft when:**-- Need to generate music from text descriptions-- Creating sound effects and environmental audio-- Building music generation applications-- Need melody-conditioned music generation-- Want stereo audio output-- Require controllable music generation with style transfer--**Key features:**-- **MusicGen**: Text-to-music generation with melody conditioning-- **AudioGen**: Text-to-sound effects generation-- **EnCodec**: High-fidelity neural audio codec-- **Multiple model sizes**: Small (300M) to Large (3.3B)-- **Stereo support**: Full stereo audio generation-- **Style conditioning**: MusicGen-Style for reference-based generation--**Use alternatives instead:**-- **Stable Audio**: For longer commercial music generation-- **Bark**: For text-to-speech with music/sound effects-- **Riffusion**: For spectogram-based music generation-- **OpenAI Jukebox**: For raw audio generation with lyrics--## Quick start--### Installation--```bash-# From PyPI-pip install audiocraft--# From GitHub (latest)-pip install git+https://github.com/facebookresearch/audiocraft.git--# Or use HuggingFace Transformers-pip install transformers torch torchaudio-```--### Basic text-to-music (AudioCraft)--```python-import torchaudio-from audiocraft.models import MusicGen--# Load model-model = MusicGen.get_pretrained('facebook/musicgen-small')--# Set generation parameters-model.set_generation_params(- duration=8, # seconds- top_k=250,- temperature=1.0-)--# Generate from text-descriptions = ["happy upbeat electronic dance music with synths"]-wav = model.generate(descriptions)--# Save audio-torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)-```--### Using HuggingFace Transformers--```python-from transformers import AutoProcessor, MusicgenForConditionalGeneration-import scipy--# Load model and processor-processor = AutoProcessor.from_pretrained("facebook/musicgen-small")-model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")-model.to("cuda")--# Generate music-inputs = processor(- text=["80s pop track with bassy drums and synth"],- padding=True,- return_tensors="pt"-).to("cuda")--audio_values = model.generate(- **inputs,- do_sample=True,- guidance_scale=3,- max_new_tokens=256-)--# Save-sampling_rate = model.config.audio_encoder.sampling_rate-scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())-```--### Text-to-sound with AudioGen--```python-from audiocraft.models import AudioGen--# Load AudioGen-model = AudioGen.get_pretrained('facebook/audiogen-medium')--model.set_generation_params(duration=5)--# Generate sound effects-descriptions = ["dog barking in a park with birds chirping"]-wav = model.generate(descriptions)--torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)-```--## Core concepts--### Architecture overview--<!-- ascii-guard-ignore -->-```-AudioCraft Architecture:-┌──────────────────────────────────────────────────────────────┐-│ Text Encoder (T5) │-│ │ │-│ Text Embeddings │-└────────────────────────┬─────────────────────────────────────┘- │-┌────────────────────────▼─────────────────────────────────────┐-│ Transformer Decoder (LM) │-│ Auto-regressively generates audio tokens │-│ Using efficient token interleaving patterns │-└────────────────────────┬─────────────────────────────────────┘- │-┌────────────────────────▼─────────────────────────────────────┐-│ EnCodec Audio Decoder │-│ Converts tokens back to audio waveform │-└──────────────────────────────────────────────────────────────┘-```-<!-- ascii-guard-ignore-end -->--### Model variants--| Model | Size | Description | Use Case |-|-------|------|-------------|----------|-| `musicgen-small` | 300M | Text-to-music | Quick generation |-| `musicgen-medium` | 1.5B | Text-to-music | Balanced |-| `musicgen-large` | 3.3B | Text-to-music | Best quality |-| `musicgen-melody` | 1.5B | Text + melody | Melody conditioning |-| `musicgen-melody-large` | 3.3B | Text + melody | Best melody |-| `musicgen-stereo-*` | Varies | Stereo output | Stereo generation |-| `musicgen-style` | 1.5B | Style transfer | Reference-based |-| `audiogen-medium` | 1.5B | Text-to-sound | Sound effects |--### Generation parameters--| Parameter | Default | Description |-|-----------|---------|-------------|-| `duration` | 8.0 | Length in seconds (1-120) |-| `top_k` | 250 | Top-k sampling |-| `top_p` | 0.0 | Nucleus sampling (0 = disabled) |-| `temperature` | 1.0 | Sampling temperature |-| `cfg_coef` | 3.0 | Classifier-free guidance |--## MusicGen usage--### Text-to-music generation--```python-from audiocraft.models import MusicGen-import torchaudio--model = MusicGen.get_pretrained('facebook/musicgen-medium')--# Configure generation-model.set_generation_params(- duration=30, # Up to 30 seconds- top_k=250, # Sampling diversity- top_p=0.0, # 0 = use top_k only- temperature=1.0, # Creativity (higher = more varied)- cfg_coef=3.0 # Text adherence (higher = stricter)-)--# Generate multiple samples-descriptions = [- "epic orchestral soundtrack with strings and brass",- "chill lo-fi hip hop beat with jazzy piano",- "energetic rock song with electric guitar"-]--# Generate (returns [batch, channels, samples])-wav = model.generate(descriptions)--# Save each-for i, audio in enumerate(wav):- torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000)-```--### Melody-conditioned generation--```python-from audiocraft.models import MusicGen-import torchaudio--# Load melody model-model = MusicGen.get_pretrained('facebook/musicgen-melody')-model.set_generation_params(duration=30)--# Load melody audio-melody, sr = torchaudio.load("melody.wav")--# Generate with melody conditioning-descriptions = ["acoustic guitar folk song"]-wav = model.generate_with_chroma(descriptions, melody, sr)--torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000)-```--### Stereo generation--```python-from audiocraft.models import MusicGen--# Load stereo model-model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')-model.set_generation_params(duration=15)--descriptions = ["ambient electronic music with wide stereo panning"]-wav = model.generate(descriptions)--# wav shape: [batch, 2, samples] for stereo-print(f"Stereo shape: {wav.shape}") # [1, 2, 480000]-torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000)-```--### Audio continuation--```python-from transformers import AutoProcessor, MusicgenForConditionalGeneration--processor = AutoProcessor.from_pretrained("facebook/musicgen-medium")-model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium")--# Load audio to continue-import torchaudio-audio, sr = torchaudio.load("intro.wav")--# Process with text and audio-inputs = processor(- audio=audio.squeeze().numpy(),- sampling_rate=sr,- text=["continue with a epic chorus"],- padding=True,- return_tensors="pt"-)--# Generate continuation-audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512)-```--## MusicGen-Style usage--### Style-conditioned generation--```python-from audiocraft.models import MusicGen--# Load style model-model = MusicGen.get_pretrained('facebook/musicgen-style')--# Configure generation with style-model.set_generation_params(- duration=30,- cfg_coef=3.0,- cfg_coef_beta=5.0 # Style influence-)--# Configure style conditioner-model.set_style_conditioner_params(- eval_q=3, # RVQ quantizers (1-6)- excerpt_length=3.0 # Style excerpt length-)--# Load style reference-style_audio, sr = torchaudio.load("reference_style.wav")--# Generate with text + style-descriptions = ["upbeat dance track"]-wav = model.generate_with_style(descriptions, style_audio, sr)-```--### Style-only generation (no text)--```python-# Generate matching style without text prompt-model.set_generation_params(- duration=30,- cfg_coef=3.0,- cfg_coef_beta=None # Disable double CFG for style-only-)--wav = model.generate_with_style([None], style_audio, sr)-```--## AudioGen usage--### Sound effect generation--```python-from audiocraft.models import AudioGen-import torchaudio--model = AudioGen.get_pretrained('facebook/audiogen-medium')-model.set_generation_params(duration=10)--# Generate various sounds-descriptions = [- "thunderstorm with heavy rain and lightning",- "busy city traffic with car horns",- "ocean waves crashing on rocks",- "crackling campfire in forest"-]--wav = model.generate(descriptions)--for i, audio in enumerate(wav):- torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)-```--## EnCodec usage--### Audio compression--```python-from audiocraft.models import CompressionModel-import torch-import torchaudio--# Load EnCodec-model = CompressionModel.get_pretrained('facebook/encodec_32khz')--# Load audio-wav, sr = torchaudio.load("audio.wav")--# Ensure correct sample rate-if sr != 32000:- resampler = torchaudio.transforms.Resample(sr, 32000)- wav = resampler(wav)--# Encode to tokens-with torch.no_grad():- encoded = model.encode(wav.unsqueeze(0))- codes = encoded[0] # Audio codes--# Decode back to audio-with torch.no_grad():- decoded = model.decode(codes)--torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)-```--## Common workflows--### Workflow 1: Music generation pipeline--```python-import torch-import torchaudio-from audiocraft.models import MusicGen--class MusicGenerator:- def __init__(self, model_name="facebook/musicgen-medium"):- self.model = MusicGen.get_pretrained(model_name)- self.sample_rate = 32000-- def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):- self.model.set_generation_params(- duration=duration,- top_k=250,- temperature=temperature,- cfg_coef=cfg- )-- with torch.no_grad():- wav = self.model.generate([prompt])-- return wav[0].cpu()-- def generate_batch(self, prompts, duration=30):- self.model.set_generation_params(duration=duration)-- with torch.no_grad():- wav = self.model.generate(prompts)-- return wav.cpu()-- def save(self, audio, path):- torchaudio.save(path, audio, sample_rate=self.sample_rate)--# Usage-generator = MusicGenerator()-audio = generator.generate(- "epic cinematic orchestral music",- duration=30,- temperature=1.0-)-generator.save(audio, "epic_music.wav")-```--### Workflow 2: Sound design batch processing--```python-import json-from pathlib import Path-from audiocraft.models import AudioGen-import torchaudio--def batch_generate_sounds(sound_specs, output_dir):- """- Generate multiple sounds from specifications.-- Args:- sound_specs: list of {"name": str, "description": str, "duration": float}- output_dir: output directory path- """- model = AudioGen.get_pretrained('facebook/audiogen-medium')- output_dir = Path(output_dir)- output_dir.mkdir(exist_ok=True)-- results = []-- for spec in sound_specs:- model.set_generation_params(duration=spec.get("duration", 5))-- wav = model.generate([spec["description"]])-- output_path = output_dir / f"{spec['name']}.wav"- torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)-- results.append({- "name": spec["name"],- "path": str(output_path),- "description": spec["description"]- })-- return results--# Usage-sounds = [- {"name": "explosion", "description": "massive explosion with debris", "duration": 3},- {"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},- {"name": "door", "description": "wooden door creaking and closing", "duration": 2}-]--results = batch_generate_sounds(sounds, "sound_effects/")-```--### Workflow 3: Gradio demo--```python-import gradio as gr-import torch-import torchaudio-from audiocraft.models import MusicGen--model = MusicGen.get_pretrained('facebook/musicgen-small')--def generate_music(prompt, duration, temperature, cfg_coef):- model.set_generation_params(- duration=duration,- temperature=temperature,- cfg_coef=cfg_coef- )-- with torch.no_grad():- wav = model.generate([prompt])-- # Save to temp file- path = "temp_output.wav"- torchaudio.save(path, wav[0].cpu(), sample_rate=32000)- return path--demo = gr.Interface(- fn=generate_music,- inputs=[- gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),- gr.Slider(1, 30, value=8, label="Duration (seconds)"),- gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),- gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")- ],- outputs=gr.Audio(label="Generated Music"),- title="MusicGen Demo"-)--demo.launch()-```--## Performance optimization--### Memory optimization--```python-# Use smaller model-model = MusicGen.get_pretrained('facebook/musicgen-small')--# Clear cache between generations-torch.cuda.empty_cache()--# Generate shorter durations-model.set_generation_params(duration=10) # Instead of 30--# Use half precision-model = model.half()-```--### Batch processing efficiency--```python-# Process multiple prompts at once (more efficient)-descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]-wav = model.generate(descriptions) # Single batch--# Instead of-for desc in descriptions:- wav = model.generate([desc]) # Multiple batches (slower)-```--### GPU memory requirements--| Model | FP32 VRAM | FP16 VRAM |-|-------|-----------|-----------|-| musicgen-small | ~4GB | ~2GB |-| musicgen-medium | ~8GB | ~4GB |-| musicgen-large | ~16GB | ~8GB |--## Common issues--| Issue | Solution |-|-------|----------|-| CUDA OOM | Use smaller model, reduce duration |-| Poor quality | Increase cfg_coef, better prompts |-| Generation too short | Check max duration setting |-| Audio artifacts | Try different temperature |-| Stereo not working | Use stereo model variant |--## References--- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md)** - Training, fine-tuning, deployment-- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md)** - Common issues and solutions--## Resources--- **GitHub**: https://github.com/facebookresearch/audiocraft-- **Paper (MusicGen)**: https://arxiv.org/abs/2306.05284-- **Paper (AudioGen)**: https://arxiv.org/abs/2209.15352-- **HuggingFace**: https://huggingface.co/facebook/musicgen-small-- **Demo**: https://huggingface.co/spaces/facebook/MusicGendiff --git a/website/docs/user-guide/skills/optional/creative/creative-auteur.md b/website/docs/user-guide/skills/optional/creative/creative-auteur.mdindex 9f1a066061f..c4a4878ea08 100644--- a/website/docs/user-guide/skills/optional/creative/creative-auteur.md+++ b/website/docs/user-guide/skills/optional/creative/creative-auteur.md@@ -21,7 +21,7 @@ Design and build cinematic, award-level web pages.| License | MIT || Platforms | linux, macos, windows || Tags | `web-design`, `cinematic`, `scroll-animation`, `design-system`, `anti-slop`, `frontend` |-| Related skills | [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`design-md`](../../bundled/creative/creative-design-md.md), [`p5js`](../../bundled/creative/creative-p5js.md) |+| Related skills | [`popular-web-designs`](../../bundled/creative/creative-popular-web-designs.md), [`design-md`](../../optional/creative/creative-design-md.md), [`p5js`](../../bundled/creative/creative-p5js.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/creative/creative-comfyui.md b/website/docs/user-guide/skills/optional/creative/creative-comfyui.mdindex e490349a254..aba8707c504 100644--- a/website/docs/user-guide/skills/optional/creative/creative-comfyui.md+++ b/website/docs/user-guide/skills/optional/creative/creative-comfyui.md@@ -21,7 +21,6 @@ Generate images, video, and audio via diffusion workflows.| License | MIT || Platforms | macos, linux, windows || Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |-| Related skills | [`stable-diffusion`](../../optional/mlops/mlops-stable-diffusion.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md b/website/docs/user-guide/skills/optional/creative/creative-design-md.mdsimilarity index 98%rename from website/docs/user-guide/skills/bundled/creative/creative-design-md.mdrename to website/docs/user-guide/skills/optional/creative/creative-design-md.mdindex 6e9a3fa8d27..397f1f34fb1 100644--- a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md+++ b/website/docs/user-guide/skills/optional/creative/creative-design-md.md@@ -14,8 +14,8 @@ Author/validate/export Google's DESIGN.md token spec files.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/creative/design-md` |+| Source | Optional — install with `hermes skills install official/creative/design-md` |+| Path | `optional-skills/creative/design-md` || Version | `1.1.0` || Author | Hermes Agent || License | MIT |diff --git a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md b/website/docs/user-guide/skills/optional/creative/creative-heartmula.mdindex fa91ac23e22..6ef31849b3f 100644--- a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md+++ b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md@@ -21,7 +21,7 @@ HeartMuLa: Suno-like song generation from lyrics + tags.| License | MIT || Platforms | linux, macos || Tags | `music`, `audio`, `generation`, `ai`, `heartmula`, `heartcodec`, `lyrics`, `songs` |-| Related skills | [`audiocraft-audio-generation`](../../optional/creative/creative-audiocraft-audio-generation.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md) |+| Related skills | [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.mdindex fa9efde06d4..3515ae317df 100644--- a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md+++ b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md@@ -21,7 +21,7 @@ Plan and run multi-agent video production pipelines.| License | MIT || Platforms | linux, macos, windows || Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |-| Related skills | [`ascii-video`](../../bundled/creative/creative-ascii-video.md), [`manim-video`](../../bundled/creative/creative-manim-video.md), [`p5js`](../../bundled/creative/creative-p5js.md), [`comfyui`](../../optional/creative/creative-comfyui.md), [`pixel-art`](../../optional/creative/creative-pixel-art.md), [`ascii-art`](../../optional/creative/creative-ascii-art.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md), [`heartmula`](../../optional/creative/creative-heartmula.md), [`songsee`](../../bundled/media/media-songsee.md), [`youtube-content`](../../bundled/media/media-youtube-content.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`concept-diagrams`](../../optional/creative/creative-concept-diagrams.md), [`baoyu-comic`](../../optional/creative/creative-baoyu-comic.md), [`baoyu-infographic`](../../bundled/creative/creative-baoyu-infographic.md), [`humanizer`](../../bundled/creative/creative-humanizer.md), [`gif-search`](../../bundled/media/media-gif-search.md), [`meme-generation`](../../optional/creative/creative-meme-generation.md) |+| Related skills | [`ascii-video`](../../bundled/creative/creative-ascii-video.md), [`manim-video`](../../bundled/creative/creative-manim-video.md), [`p5js`](../../bundled/creative/creative-p5js.md), [`comfyui`](../../optional/creative/creative-comfyui.md), [`pixel-art`](../../optional/creative/creative-pixel-art.md), [`ascii-art`](../../optional/creative/creative-ascii-art.md), [`songwriting-and-ai-music`](../../bundled/creative/creative-songwriting-and-ai-music.md), [`heartmula`](../../optional/creative/creative-heartmula.md), [`songsee`](../../optional/media/media-songsee.md), [`youtube-content`](../../bundled/media/media-youtube-content.md), [`claude-design`](../../bundled/creative/creative-claude-design.md), [`excalidraw`](../../optional/creative/creative-excalidraw.md), [`architecture-diagram`](../../bundled/creative/creative-architecture-diagram.md), [`concept-diagrams`](../../optional/creative/creative-concept-diagrams.md), [`baoyu-comic`](../../optional/creative/creative-baoyu-comic.md), [`baoyu-infographic`](../../bundled/creative/creative-baoyu-infographic.md), [`humanizer`](../../bundled/creative/creative-humanizer.md), [`gif-search`](../../optional/media/media-gif-search.md), [`meme-generation`](../../optional/creative/creative-meme-generation.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.mdindex 6d2710e81bd..55cfb97dc15 100644--- a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md+++ b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md@@ -640,7 +640,7 @@ B105: =B88/(1+(E48-0.07)) // Doesn't recalculate full DCF**Why it's wrong:**- Can't verify where data came from-- Fails xlsx skill requirements+- Fails `microsoft-office` skill requirements- Not audit-ready- Wastes time fixing later@@ -705,7 +705,7 @@ This vertical layout makes it hard to see the progression across years within ea**Why it's wrong:**- Can't distinguish inputs from formulas- Auditing becomes impossible-- Violates xlsx skill requirements+- Violates `microsoft-office` skill requirements**Instead:** Blue text for ALL hardcoded inputs, black text for ALL formulas, green for sheet links@@ -765,13 +765,13 @@ In addition, be aware of these errors:## Excel File Creation-**This skill uses the `xlsx` skill for all spreadsheet operations.** The xlsx skill provides:+**This skill uses the `microsoft-office` skill for all spreadsheet operations.** It provides:- Standardized formula construction rules- Number formatting conventions- Automated formula recalculation via `recalc.py` script- Comprehensive error checking and validation-All Excel files created by this skill must follow xlsx skill requirements, including zero formula errors and proper recalculation.+All Excel files created by this skill must follow `microsoft-office` skill requirements, including zero formula errors and proper recalculation.## Quality Rubric@@ -852,11 +852,11 @@ The script will:### Formatting Standards-**IMPORTANT**: Follow the xlsx skill for formula construction rules and number formatting conventions. The DCF skill adds specific visual presentation standards.+**IMPORTANT**: Follow the `microsoft-office` skill for formula construction rules and number formatting conventions. The DCF skill adds specific visual presentation standards.**Color Scheme - Two Layers**:-**Layer 1: Font Colors (MANDATORY from xlsx skill)**+**Layer 1: Font Colors (MANDATORY from `microsoft-office` skill)**- **Blue text (RGB: 0,0,255)**: ALL hardcoded inputs (stock price, shares, historical data, assumptions)- **Black text (RGB: 0,0,0)**: ALL formulas and calculations- **Green text (RGB: 0,128,0)**: Links to other sheets (WACC sheet references)@@ -902,7 +902,7 @@ The script will:**Borders are mandatory** - models without professional borders are not client-ready.-**Number Formats** (follows xlsx skill standards):+**Number Formats** (follows `microsoft-office` skill standards):- **Years**: Format as text strings (e.g., "2024" not "2,024")- **Percentages**: `0.0%` (one decimal place)- **Currency**: `$#,##0` for millions; `$#,##0.00` for per-share - ALWAYS specify units in headers ("Revenue ($mm)")@@ -912,7 +912,7 @@ The script will:**Cell Comments (MANDATORY for all hardcoded inputs)**:-Per the xlsx skill, ALL hardcoded values must have cell comments documenting the source. Format: "Source: [System/Document], [Date], [Reference], [URL if applicable]"+Per the `microsoft-office` skill, ALL hardcoded values must have cell comments documenting the source. Format: "Source: [System/Document], [Date], [Reference], [URL if applicable]"**CRITICAL**: Add comments AS CELLS ARE CREATED. Do not defer to the end.@@ -1217,7 +1217,7 @@ This approach centralizes scenario logic, making the model easier to audit and m### During Model Construction1. **Build Excel model** using openpyxl with formulas (not hardcoded values)-2. **Follow xlsx skill conventions** for formula construction and formatting+2. **Follow `microsoft-office` skill conventions** for formula construction and formatting3. **Apply fill colors only if requested** by user or if specific brand guidelines are provided### Before Delivering Model (MANDATORY)diff --git a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md b/website/docs/user-guide/skills/optional/finance/finance-excel-author.mdindex 729add34ec6..ed1a459f602 100644--- a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md+++ b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md@@ -21,7 +21,7 @@ Build auditable financial workbooks headless via openpyxl.| License | Apache-2.0 || Platforms | linux, macos, windows || Tags | `excel`, `openpyxl`, `finance`, `spreadsheet`, `modeling` |-| Related skills | [`xlsx`](../../bundled/productivity/productivity-xlsx.md), [`pptx-author`](../../optional/finance/finance-pptx-author.md), [`dcf-model`](../../optional/finance/finance-dcf-model.md), [`comps-analysis`](../../optional/finance/finance-comps-analysis.md), [`lbo-model`](../../optional/finance/finance-lbo-model.md), [`3-statement-model`](../../optional/finance/finance-3-statement-model.md) |+| Related skills | [`microsoft-office`](../../bundled/productivity/productivity-microsoft-office.md), [`pptx-author`](../../optional/finance/finance-pptx-author.md), [`dcf-model`](../../optional/finance/finance-dcf-model.md), [`comps-analysis`](../../optional/finance/finance-comps-analysis.md), [`lbo-model`](../../optional/finance/finance-lbo-model.md), [`3-statement-model`](../../optional/finance/finance-3-statement-model.md) |## Reference: full SKILL.md@@ -48,7 +48,7 @@ it). Otherwise, when `hermes` is on PATH, let Hermes build its shared, pinneddocuments environment under the Hermes home (safe to run from several agentsat once); in a Docker sandbox without Hermes the block builds a venv in thesandbox home with the same pinned versions. It is the same block as the-docx/xlsx/powerpoint/pdf skills. Never `pip install` into the interpreter that+microsoft-office/pdf skills. Never `pip install` into the interpreter thatruns Hermes:```bashdiff --git a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.mdindex 8c3e80e05d7..8ad8c51d18f 100644--- a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md+++ b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md@@ -21,7 +21,7 @@ Build PowerPoint decks headless with python-pptx.| License | Apache-2.0 || Platforms | linux, macos, windows || Tags | `powerpoint`, `pptx`, `python-pptx`, `presentation`, `finance` |-| Related skills | [`excel-author`](../../optional/finance/finance-excel-author.md), [`powerpoint`](../../bundled/productivity/productivity-powerpoint.md) |+| Related skills | [`excel-author`](../../optional/finance/finance-excel-author.md), [`microsoft-office`](../../bundled/productivity/productivity-microsoft-office.md) |## Reference: full SKILL.md@@ -35,7 +35,7 @@ Produce a .pptx file on disk using `python-pptx`. Use when you need to deliver aAdapted from Anthropic's `pptx-author` and `pitch-deck` skills in [anthropics/financial-services](https://github.com/anthropics/financial-services). The MCP / Office-JS branches of the originals are dropped — this assumes headless Python.-For the broader, already-shipped PowerPoint authoring skill (slides, speaker notes, embeds, media), see the built-in `powerpoint` skill. This skill is a lighter-weight pattern tuned for model-backed decks (pitch decks, IC memos, earnings notes) where every number must trace to a source workbook.+For the broader, already-shipped PowerPoint authoring skill (slides, speaker notes, embeds, media), see the built-in `microsoft-office` skill. This skill is a lighter-weight pattern tuned for model-backed decks (pitch decks, IC memos, earnings notes) where every number must trace to a source workbook.## Output contract@@ -49,7 +49,7 @@ it). Otherwise, when `hermes` is on PATH, let Hermes build its shared, pinneddocuments environment under the Hermes home (safe to run from several agentsat once); in a Docker sandbox without Hermes the block builds a venv in thesandbox home with the same pinned versions. It is the same block as the-docx/xlsx/powerpoint/pdf skills. Never `pip install` into the interpreter that+microsoft-office/pdf skills. Never `pip install` into the interpreter thatruns Hermes:```bash@@ -213,8 +213,8 @@ A typical banking pitch deck follows this structure. Not prescriptive, but usefu## When NOT to use this skill- Users in a live PowerPoint session with an Office MCP available — drive their live doc instead.-- Non-financial slideware (quarterly all-hands, marketing decks) — use the broader `powerpoint` skill.-- Decks with heavy animation, transitions, or speaker notes — use the broader `powerpoint` skill.+- Non-financial slideware (quarterly all-hands, marketing decks) — use the broader `microsoft-office` skill.+- Decks with heavy animation, transitions, or speaker notes — use the broader `microsoft-office` skill.## Attributiondiff --git a/website/docs/user-guide/skills/bundled/media/media-gif-search.md b/website/docs/user-guide/skills/optional/media/media-gif-search.mdsimilarity index 93%rename from website/docs/user-guide/skills/bundled/media/media-gif-search.mdrename to website/docs/user-guide/skills/optional/media/media-gif-search.mdindex 31d0e03eb88..2f971e0892b 100644--- a/website/docs/user-guide/skills/bundled/media/media-gif-search.md+++ b/website/docs/user-guide/skills/optional/media/media-gif-search.md@@ -14,8 +14,8 @@ Search/download GIFs from Tenor via curl + jq.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/media/gif-search` |+| Source | Optional — install with `hermes skills install official/media/gif-search` |+| Path | `optional-skills/media/gif-search` || Version | `1.1.0` || Author | Hermes Agent || License | MIT |@@ -103,4 +103,4 @@ Each result has multiple formats under `.media_formats`:- URL-encode the query: spaces as `+`, special chars as `%XX`- For sending in chat, `tinygif` URLs are lighter weight-- GIF URLs can be used directly in markdown: ``+- GIF URLs can be used directly in markdown: ``diff --git a/website/docs/user-guide/skills/bundled/media/media-songsee.md b/website/docs/user-guide/skills/optional/media/media-songsee.mdsimilarity index 95%rename from website/docs/user-guide/skills/bundled/media/media-songsee.mdrename to website/docs/user-guide/skills/optional/media/media-songsee.mdindex dd1e1d3d5ee..ff791fef0bb 100644--- a/website/docs/user-guide/skills/bundled/media/media-songsee.md+++ b/website/docs/user-guide/skills/optional/media/media-songsee.md@@ -14,8 +14,8 @@ Audio spectrograms/features (mel, chroma, MFCC) via CLI.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/media/songsee` |+| Source | Optional — install with `hermes skills install official/media/songsee` |+| Path | `optional-skills/media/songsee` || Version | `1.0.0` || Author | community || License | MIT |diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md b/website/docs/user-guide/skills/optional/mlops/mlops-clip.mddeleted file mode 100644index e9266e443b2..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md+++ /dev/null@@ -1,272 +0,0 @@-----title: "Clip — Zero-shot image classification and image-text search"-sidebar_label: "Clip"-description: "Zero-shot image classification and image-text search"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Clip--Zero-shot image classification and image-text search.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/clip` |-| Path | `optional-skills/mlops/clip` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `transformers`, `torch`, `pillow` |-| Platforms | linux, macos, windows |-| Tags | `Multimodal`, `CLIP`, `Vision-Language`, `Zero-Shot`, `Image Classification`, `OpenAI`, `Image Search`, `Cross-Modal Retrieval`, `Content Moderation` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# CLIP - Contrastive Language-Image Pre-Training--OpenAI's model that understands images from natural language.--## When to use CLIP--**Use when:**-- Zero-shot image classification (no training data needed)-- Image-text similarity/matching-- Semantic image search-- Content moderation (detect NSFW, violence)-- Visual question answering-- Cross-modal retrieval (image→text, text→image)--**Metrics**:-- **25,300+ GitHub stars**-- Trained on 400M image-text pairs-- Matches ResNet-50 on ImageNet (zero-shot)-- MIT License--**Use alternatives instead**:-- **BLIP-2**: Better captioning-- **LLaVA**: Vision-language chat-- **Segment Anything**: Image segmentation--## Quick start--### Installation--```bash-pip install git+https://github.com/openai/CLIP.git-pip install torch torchvision ftfy regex tqdm-```--### Zero-shot classification--```python-import torch-import clip-from PIL import Image--# Load model-device = "cuda" if torch.cuda.is_available() else "cpu"-model, preprocess = clip.load("ViT-B/32", device=device)--# Load image-image = preprocess(Image.open("photo.jpg")).unsqueeze(0).to(device)--# Define possible labels-text = clip.tokenize(["a dog", "a cat", "a bird", "a car"]).to(device)--# Compute similarity-with torch.no_grad():- image_features = model.encode_image(image)- text_features = model.encode_text(text)-- # Cosine similarity- logits_per_image, logits_per_text = model(image, text)- probs = logits_per_image.softmax(dim=-1).cpu().numpy()--# Print results-labels = ["a dog", "a cat", "a bird", "a car"]-for label, prob in zip(labels, probs[0]):- print(f"{label}: {prob:.2%}")-```--## Available models--```python-# Models (sorted by size)-models = [- "RN50", # ResNet-50- "RN101", # ResNet-101- "ViT-B/32", # Vision Transformer (recommended)- "ViT-B/16", # Better quality, slower- "ViT-L/14", # Best quality, slowest-]--model, preprocess = clip.load("ViT-B/32")-```--| Model | Parameters | Speed | Quality |-|-------|------------|-------|---------|-| RN50 | 102M | Fast | Good |-| ViT-B/32 | 151M | Medium | Better |-| ViT-L/14 | 428M | Slow | Best |--## Image-text similarity--```python-# Compute embeddings-image_features = model.encode_image(image)-text_features = model.encode_text(text)--# Normalize-image_features /= image_features.norm(dim=-1, keepdim=True)-text_features /= text_features.norm(dim=-1, keepdim=True)--# Cosine similarity-similarity = (image_features @ text_features.T).item()-print(f"Similarity: {similarity:.4f}")-```--## Semantic image search--```python-# Index images-image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]-image_embeddings = []--for img_path in image_paths:- image = preprocess(Image.open(img_path)).unsqueeze(0).to(device)- with torch.no_grad():- embedding = model.encode_image(image)- embedding /= embedding.norm(dim=-1, keepdim=True)- image_embeddings.append(embedding)--image_embeddings = torch.cat(image_embeddings)--# Search with text query-query = "a sunset over the ocean"-text_input = clip.tokenize([query]).to(device)-with torch.no_grad():- text_embedding = model.encode_text(text_input)- text_embedding /= text_embedding.norm(dim=-1, keepdim=True)--# Find most similar images-similarities = (text_embedding @ image_embeddings.T).squeeze(0)-top_k = similarities.topk(3)--for idx, score in zip(top_k.indices, top_k.values):- print(f"{image_paths[idx]}: {score:.3f}")-```--## Content moderation--```python-# Define categories-categories = [- "safe for work",- "not safe for work",- "violent content",- "graphic content"-]--text = clip.tokenize(categories).to(device)--# Check image-with torch.no_grad():- logits_per_image, _ = model(image, text)- probs = logits_per_image.softmax(dim=-1)--# Get classification-max_idx = probs.argmax().item()-max_prob = probs[0, max_idx].item()--print(f"Category: {categories[max_idx]} ({max_prob:.2%})")-```--## Batch processing--```python-# Process multiple images-images = [preprocess(Image.open(f"img{i}.jpg")) for i in range(10)]-images = torch.stack(images).to(device)--with torch.no_grad():- image_features = model.encode_image(images)- image_features /= image_features.norm(dim=-1, keepdim=True)--# Batch text-texts = ["a dog", "a cat", "a bird"]-text_tokens = clip.tokenize(texts).to(device)--with torch.no_grad():- text_features = model.encode_text(text_tokens)- text_features /= text_features.norm(dim=-1, keepdim=True)--# Similarity matrix (10 images × 3 texts)-similarities = image_features @ text_features.T-print(similarities.shape) # (10, 3)-```--## Integration with vector databases--```python-# Store CLIP embeddings in Chroma/FAISS-import chromadb--client = chromadb.Client()-collection = client.create_collection("image_embeddings")--# Add image embeddings-for img_path, embedding in zip(image_paths, image_embeddings):- collection.add(- embeddings=[embedding.cpu().numpy().tolist()],- metadatas=[{"path": img_path}],- ids=[img_path]- )--# Query with text-query = "a sunset"-text_embedding = model.encode_text(clip.tokenize([query]))-results = collection.query(- query_embeddings=[text_embedding.cpu().numpy().tolist()],- n_results=5-)-```--## Best practices--1. **Use ViT-B/32 for most cases** - Good balance-2. **Normalize embeddings** - Required for cosine similarity-3. **Batch processing** - More efficient-4. **Cache embeddings** - Expensive to recompute-5. **Use descriptive labels** - Better zero-shot performance-6. **GPU recommended** - 10-50× faster-7. **Preprocess images** - Use provided preprocess function--## Performance--| Operation | CPU | GPU (V100) |-|-----------|-----|------------|-| Image encoding | ~200ms | ~20ms |-| Text encoding | ~50ms | ~5ms |-| Similarity compute | <1ms | <1ms |--## Limitations--1. **Not for fine-grained tasks** - Best for broad categories-2. **Requires descriptive text** - Vague labels perform poorly-3. **Biased on web data** - May have dataset biases-4. **No bounding boxes** - Whole image only-5. **Limited spatial understanding** - Position/counting weak--## Resources--- **GitHub**: https://github.com/openai/CLIP ⭐ 25,300+-- **Paper**: https://arxiv.org/abs/2103.00020-- **Colab**: https://colab.research.google.com/github/openai/clip/-- **License**: MITdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md b/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.mddeleted file mode 100644index d94837dd03c..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md+++ /dev/null@@ -1,613 +0,0 @@-----title: "Weights And Biases — W&B: log ML experiments, sweeps, model registry, dashboards"-sidebar_label: "Weights And Biases"-description: "W&B: log ML experiments, sweeps, model registry, dashboards"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Weights And Biases--W&B: log ML experiments, sweeps, model registry, dashboards.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/weights-and-biases` |-| Path | `optional-skills/mlops/evaluation/weights-and-biases` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `wandb` |-| Platforms | linux, macos, windows |-| Tags | `MLOps`, `Weights And Biases`, `WandB`, `Experiment Tracking`, `Hyperparameter Tuning`, `Model Registry`, `Collaboration`, `Real-Time Visualization`, `PyTorch`, `TensorFlow`, `HuggingFace` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Weights & Biases: ML Experiment Tracking & MLOps--## When to Use This Skill--Use Weights & Biases (W&B) when you need to:-- **Track ML experiments** with automatic metric logging-- **Visualize training** in real-time dashboards-- **Compare runs** across hyperparameters and configurations-- **Optimize hyperparameters** with automated sweeps-- **Manage model registry** with versioning and lineage-- **Collaborate on ML projects** with team workspaces-- **Track artifacts** (datasets, models, code) with lineage--**Users**: 200,000+ ML practitioners | **GitHub Stars**: 10.5k+ | **Integrations**: 100+--## Installation--```bash-# Install W&B-pip install wandb--# Login (creates API key)-wandb login--# Or set API key programmatically-export WANDB_API_KEY=your_api_key_here-```--## Quick Start--### Basic Experiment Tracking--```python-import wandb--# Initialize a run-run = wandb.init(- project="my-project",- config={- "learning_rate": 0.001,- "epochs": 10,- "batch_size": 32,- "architecture": "ResNet50"- }-)--# Training loop-for epoch in range(run.config.epochs):- # Your training code- train_loss = train_epoch()- val_loss = validate()-- # Log metrics- wandb.log({- "epoch": epoch,- "train/loss": train_loss,- "val/loss": val_loss,- "train/accuracy": train_acc,- "val/accuracy": val_acc- })--# Finish the run-wandb.finish()-```--### With PyTorch--```python-import torch-import wandb--# Initialize-wandb.init(project="pytorch-demo", config={- "lr": 0.001,- "epochs": 10-})--# Access config-config = wandb.config--# Training loop-for epoch in range(config.epochs):- for batch_idx, (data, target) in enumerate(train_loader):- # Forward pass- output = model(data)- loss = criterion(output, target)-- # Backward pass- optimizer.zero_grad()- loss.backward()- optimizer.step()-- # Log every 100 batches- if batch_idx % 100 == 0:- wandb.log({- "loss": loss.item(),- "epoch": epoch,- "batch": batch_idx- })--# Save model-torch.save(model.state_dict(), "model.pth")-wandb.save("model.pth") # Upload to W&B--wandb.finish()-```--## Core Concepts--### 1. Projects and Runs--**Project**: Collection of related experiments-**Run**: Single execution of your training script--```python-# Create/use project-run = wandb.init(- project="image-classification",- name="resnet50-experiment-1", # Optional run name- tags=["baseline", "resnet"], # Organize with tags- notes="First baseline run" # Add notes-)--# Each run has unique ID-print(f"Run ID: {run.id}")-print(f"Run URL: {run.url}")-```--### 2. Configuration Tracking--Track hyperparameters automatically:--```python-config = {- # Model architecture- "model": "ResNet50",- "pretrained": True,-- # Training params- "learning_rate": 0.001,- "batch_size": 32,- "epochs": 50,- "optimizer": "Adam",-- # Data params- "dataset": "ImageNet",- "augmentation": "standard"-}--wandb.init(project="my-project", config=config)--# Access config during training-lr = wandb.config.learning_rate-batch_size = wandb.config.batch_size-```--### 3. Metric Logging--```python-# Log scalars-wandb.log({"loss": 0.5, "accuracy": 0.92})--# Log multiple metrics-wandb.log({- "train/loss": train_loss,- "train/accuracy": train_acc,- "val/loss": val_loss,- "val/accuracy": val_acc,- "learning_rate": current_lr,- "epoch": epoch-})--# Log with custom x-axis-wandb.log({"loss": loss}, step=global_step)--# Log media (images, audio, video)-wandb.log({"examples": [wandb.Image(img) for img in images]})--# Log histograms-wandb.log({"gradients": wandb.Histogram(gradients)})--# Log tables-table = wandb.Table(columns=["id", "prediction", "ground_truth"])-wandb.log({"predictions": table})-```--### 4. Model Checkpointing--```python-import torch-import wandb--# Save model checkpoint-checkpoint = {- 'epoch': epoch,- 'model_state_dict': model.state_dict(),- 'optimizer_state_dict': optimizer.state_dict(),- 'loss': loss,-}--torch.save(checkpoint, 'checkpoint.pth')--# Upload to W&B-wandb.save('checkpoint.pth')--# Or use Artifacts (recommended)-artifact = wandb.Artifact('model', type='model')-artifact.add_file('checkpoint.pth')-wandb.log_artifact(artifact)-```--## Hyperparameter Sweeps--Automatically search for optimal hyperparameters.--### Define Sweep Configuration--```python-sweep_config = {- 'method': 'bayes', # or 'grid', 'random'- 'metric': {- 'name': 'val/accuracy',- 'goal': 'maximize'- },- 'parameters': {- 'learning_rate': {- 'distribution': 'log_uniform_values',- 'min': 1e-5,- 'max': 1e-1- },- 'batch_size': {- 'values': [16, 32, 64, 128]- },- 'optimizer': {- 'values': ['adam', 'sgd', 'rmsprop']- },- 'dropout': {- 'distribution': 'uniform',- 'min': 0.1,- 'max': 0.5- }- }-}--# Initialize sweep-sweep_id = wandb.sweep(sweep_config, project="my-project")-```--### Define Training Function--```python-def train():- # Initialize run- run = wandb.init()-- # Access sweep parameters- lr = wandb.config.learning_rate- batch_size = wandb.config.batch_size- optimizer_name = wandb.config.optimizer-- # Build model with sweep config- model = build_model(wandb.config)- optimizer = get_optimizer(optimizer_name, lr)-- # Training loop- for epoch in range(NUM_EPOCHS):- train_loss = train_epoch(model, optimizer, batch_size)- val_acc = validate(model)-- # Log metrics- wandb.log({- "train/loss": train_loss,- "val/accuracy": val_acc- })--# Run sweep-wandb.agent(sweep_id, function=train, count=50) # Run 50 trials-```--### Sweep Strategies--```python-# Grid search - exhaustive-sweep_config = {- 'method': 'grid',- 'parameters': {- 'lr': {'values': [0.001, 0.01, 0.1]},- 'batch_size': {'values': [16, 32, 64]}- }-}--# Random search-sweep_config = {- 'method': 'random',- 'parameters': {- 'lr': {'distribution': 'uniform', 'min': 0.0001, 'max': 0.1},- 'dropout': {'distribution': 'uniform', 'min': 0.1, 'max': 0.5}- }-}--# Bayesian optimization (recommended)-sweep_config = {- 'method': 'bayes',- 'metric': {'name': 'val/loss', 'goal': 'minimize'},- 'parameters': {- 'lr': {'distribution': 'log_uniform_values', 'min': 1e-5, 'max': 1e-1}- }-}-```--## Artifacts--Track datasets, models, and other files with lineage.--### Log Artifacts--```python-# Create artifact-artifact = wandb.Artifact(- name='training-dataset',- type='dataset',- description='ImageNet training split',- metadata={'size': '1.2M images', 'split': 'train'}-)--# Add files-artifact.add_file('data/train.csv')-artifact.add_dir('data/images/')--# Log artifact-wandb.log_artifact(artifact)-```--### Use Artifacts--```python-# Download and use artifact-run = wandb.init(project="my-project")--# Download artifact-artifact = run.use_artifact('training-dataset:latest')-artifact_dir = artifact.download()--# Use the data-data = load_data(f"{artifact_dir}/train.csv")-```--### Model Registry--```python-# Log model as artifact-model_artifact = wandb.Artifact(- name='resnet50-model',- type='model',- metadata={'architecture': 'ResNet50', 'accuracy': 0.95}-)--model_artifact.add_file('model.pth')-wandb.log_artifact(model_artifact, aliases=['best', 'production'])--# Link to model registry-run.link_artifact(model_artifact, 'model-registry/production-models')-```--## Integration Examples--### HuggingFace Transformers--```python-from transformers import Trainer, TrainingArguments-import wandb--# Initialize W&B-wandb.init(project="hf-transformers")--# Training arguments with W&B-training_args = TrainingArguments(- output_dir="./results",- report_to="wandb", # Enable W&B logging- run_name="bert-finetuning",- logging_steps=100,- save_steps=500-)--# Trainer automatically logs to W&B-trainer = Trainer(- model=model,- args=training_args,- train_dataset=train_dataset,- eval_dataset=eval_dataset-)--trainer.train()-```--### PyTorch Lightning--```python-from pytorch_lightning import Trainer-from pytorch_lightning.loggers import WandbLogger-import wandb--# Create W&B logger-wandb_logger = WandbLogger(- project="lightning-demo",- log_model=True # Log model checkpoints-)--# Use with Trainer-trainer = Trainer(- logger=wandb_logger,- max_epochs=10-)--trainer.fit(model, datamodule=dm)-```--### Keras/TensorFlow--```python-import wandb-from wandb.integration.keras import WandbMetricsLogger, WandbModelCheckpoint--# Initialize-wandb.init(project="keras-demo")--# Add callbacks (the monolithic WandbCallback was removed;-# use the dedicated callbacks from wandb.integration.keras instead)-model.fit(- x_train, y_train,- validation_data=(x_val, y_val),- epochs=10,- callbacks=[- WandbMetricsLogger(), # Auto-logs metrics- WandbModelCheckpoint("models/model-{epoch}") # Saves checkpoints- ]-)-```--## Visualization & Analysis--### Custom Charts--```python-# Log custom visualizations-import matplotlib.pyplot as plt--fig, ax = plt.subplots()-ax.plot(x, y)-wandb.log({"custom_plot": wandb.Image(fig)})--# Log confusion matrix-wandb.log({"conf_mat": wandb.plot.confusion_matrix(- probs=None,- y_true=ground_truth,- preds=predictions,- class_names=class_names-)})-```--### Reports--Create shareable reports in W&B UI:-- Combine runs, charts, and text-- Markdown support-- Embeddable visualizations-- Team collaboration--## Best Practices--### 1. Organize with Tags and Groups--```python-wandb.init(- project="my-project",- tags=["baseline", "resnet50", "imagenet"],- group="resnet-experiments", # Group related runs- job_type="train" # Type of job-)-```--### 2. Log Everything Relevant--```python-# Log system metrics-wandb.log({- "gpu/util": gpu_utilization,- "gpu/memory": gpu_memory_used,- "cpu/util": cpu_utilization-})--# Log code version-wandb.log({"git_commit": git_commit_hash})--# Log data splits-wandb.log({- "data/train_size": len(train_dataset),- "data/val_size": len(val_dataset)-})-```--### 3. Use Descriptive Names--```python-# ✅ Good: Descriptive run names-wandb.init(- project="nlp-classification",- name="bert-base-lr0.001-bs32-epoch10"-)--# ❌ Bad: Generic names-wandb.init(project="nlp", name="run1")-```--### 4. Save Important Artifacts--```python-# Save final model-artifact = wandb.Artifact('final-model', type='model')-artifact.add_file('model.pth')-wandb.log_artifact(artifact)--# Save predictions for analysis-predictions_table = wandb.Table(- columns=["id", "input", "prediction", "ground_truth"],- data=predictions_data-)-wandb.log({"predictions": predictions_table})-```--### 5. Use Offline Mode for Unstable Connections--```python-import os--# Enable offline mode-os.environ["WANDB_MODE"] = "offline"--wandb.init(project="my-project")-# ... your code ...--# Sync later-# wandb sync <run_directory>-```--## Team Collaboration--### Share Runs--```python-# Runs are automatically shareable via URL-run = wandb.init(project="team-project")-print(f"Share this URL: {run.url}")-```--### Team Projects--- Create team account at wandb.ai-- Add team members-- Set project visibility (private/public)-- Use team-level artifacts and model registry--## Pricing--- **Free**: Unlimited public projects, 100GB storage-- **Academic**: Free for students/researchers-- **Teams**: $50/seat/month, private projects, unlimited storage-- **Enterprise**: Custom pricing, on-prem options--## Resources--- **Documentation**: https://docs.wandb.ai-- **GitHub**: https://github.com/wandb/wandb (10.5k+ stars)-- **Examples**: https://github.com/wandb/examples-- **Community**: https://wandb.ai/community-- **Discord**: https://wandb.me/discord--## See Also--- `references/sweeps.md` - Comprehensive hyperparameter optimization guide-- `references/artifacts.md` - Data and model versioning patterns-- `references/integrations.md` - Framework-specific examplesdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md b/website/docs/user-guide/skills/optional/mlops/mlops-guidance.mddeleted file mode 100644index d8f7de7512a..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md+++ /dev/null@@ -1,595 +0,0 @@-----title: "Guidance — Constrain LLM output with grammars; guarantee valid JSON"-sidebar_label: "Guidance"-description: "Constrain LLM output with grammars; guarantee valid JSON"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Guidance--Constrain LLM output with grammars; guarantee valid JSON.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/guidance` |-| Path | `optional-skills/mlops/guidance` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `guidance`, `transformers` |-| Platforms | linux, macos, windows |-| Tags | `Prompt Engineering`, `Guidance`, `Constrained Generation`, `Structured Output`, `JSON Validation`, `Grammar`, `Microsoft Research`, `Format Enforcement`, `Multi-Step Workflows` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Guidance: Constrained LLM Generation--## When to Use This Skill--Use Guidance when you need to:-- **Control LLM output syntax** with regex or grammars-- **Guarantee valid JSON/XML/code** generation-- **Reduce latency** vs traditional prompting approaches-- **Enforce structured formats** (dates, emails, IDs, etc.)-- **Build multi-step workflows** with Pythonic control flow-- **Prevent invalid outputs** through grammatical constraints--**GitHub Stars**: 18,000+ | **From**: Microsoft Research--## Installation--```bash-# Base installation-pip install guidance--# With specific backends-pip install guidance[transformers] # Hugging Face models-pip install guidance[llama_cpp] # llama.cpp models-```--## Quick Start--### Basic Example: Structured Generation--```python-from guidance import models, gen--# Load model (supports OpenAI, Transformers, llama.cpp)-lm = models.OpenAI("gpt-4")--# Generate with constraints-result = lm + "The capital of France is " + gen("capital", max_tokens=5)--print(result["capital"]) # "Paris"-```--### Chat format with a local model--> **Constraint support requires local logit access.** Regex, `select()`, and-> grammar-based constrained generation only work with local backends-> (`Transformers`, `LlamaCpp`). Remote API backends (`OpenAI`, and Azure-> variants) support unconstrained `gen()` / chat only — they cannot enforce-> token-level constraints. guidance 0.3.x has no `models.Anthropic` class.--```python-from guidance import models, gen, system, user, assistant--# Local model (supports constrained generation)-lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# Use context managers for chat format-with system():- lm += "You are a helpful assistant."--with user():- lm += "What is the capital of France?"--with assistant():- lm += gen(max_tokens=20)-```--## Core Concepts--### 1. Context Managers--Guidance uses Pythonic context managers for chat-style interactions.--```python-from guidance import system, user, assistant, gen--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# System message-with system():- lm += "You are a JSON generation expert."--# User message-with user():- lm += "Generate a person object with name and age."--# Assistant response-with assistant():- lm += gen("response", max_tokens=100)--print(lm["response"])-```--**Benefits:**-- Natural chat flow-- Clear role separation-- Easy to read and maintain--### 2. Constrained Generation--Guidance ensures outputs match specified patterns using regex or grammars.--#### Regex Constraints--```python-from guidance import models, gen--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# Constrain to valid email format-lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")--# Constrain to date format (YYYY-MM-DD)-lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}")--# Constrain to phone number-lm += "Phone: " + gen("phone", regex=r"\d{3}-\d{3}-\d{4}")--print(lm["email"]) # Guaranteed valid email-print(lm["date"]) # Guaranteed YYYY-MM-DD format-```--**How it works:**-- Regex converted to grammar at token level-- Invalid tokens filtered during generation-- Model can only produce matching outputs--#### Selection Constraints--```python-from guidance import models, gen, select--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# Constrain to specific choices-lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")--# Multiple-choice selection-lm += "Best answer: " + select(- ["A) Paris", "B) London", "C) Berlin", "D) Madrid"],- name="answer"-)--print(lm["sentiment"]) # One of: positive, negative, neutral-print(lm["answer"]) # One of: A, B, C, or D-```--### 3. Token Healing--Guidance automatically "heals" token boundaries between prompt and generation.--**Problem:** Tokenization creates unnatural boundaries.--```python-# Without token healing-prompt = "The capital of France is "-# Last token: " is "-# First generated token might be " Par" (with leading space)-# Result: "The capital of France is Paris" (double space!)-```--**Solution:** Guidance backs up one token and regenerates.--```python-from guidance import models, gen--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# Token healing enabled by default-lm += "The capital of France is " + gen("capital", max_tokens=5)-# Result: "The capital of France is Paris" (correct spacing)-```--**Benefits:**-- Natural text boundaries-- No awkward spacing issues-- Better model performance (sees natural token sequences)--### 4. Grammar-Based Generation--Define complex structures by composing grammar functions. The template-string-`grammar=` form is not part of current guidance — build grammars from-composable functions, or use `guidance.json()` for JSON.--```python-from guidance import models, gen-from guidance import json as gen_json-from pydantic import BaseModel, Field--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--# JSON via a Pydantic schema (guidance.json compiles the schema to a grammar)-class Person(BaseModel):- name: str = Field(pattern=r"[A-Za-z ]+")- age: int- email: str = Field(pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")--lm += gen_json(name="person", schema=Person)--print(lm["person"]) # Guaranteed valid JSON matching the schema--# Or compose grammar functions directly:-grammar = "name=" + gen("name", regex=r"[A-Za-z ]+") + " age=" + gen("age", regex=r"[0-9]+")-lm += grammar-```--**Use cases:**-- Complex structured outputs-- Nested data structures-- Programming language syntax-- Domain-specific languages--### 5. Guidance Functions--Create reusable generation patterns with the `@guidance` decorator.--```python-from guidance import guidance, gen, models--@guidance-def generate_person(lm):- """Generate a person with name and age."""- lm += "Name: " + gen("name", max_tokens=20, stop="\n")- lm += "\nAge: " + gen("age", regex=r"[0-9]+", max_tokens=3)- return lm--# Use the function-lm = models.Transformers("microsoft/Phi-4-mini-instruct")-lm = generate_person(lm)--print(lm["name"])-print(lm["age"])-```--**Stateful Functions:**--```python-@guidance(stateless=False)-def react_agent(lm, question, tools, max_rounds=5):- """ReAct agent with tool use."""- lm += f"Question: {question}\n\n"-- for i in range(max_rounds):- # Thought- lm += f"Thought {i+1}: " + gen("thought", stop="\n")-- # Action- lm += "\nAction: " + select(list(tools.keys()), name="action")-- # Execute tool- tool_result = tools[lm["action"]]()- lm += f"\nObservation: {tool_result}\n\n"-- # Check if done- lm += "Done? " + select(["Yes", "No"], name="done")- if lm["done"] == "Yes":- break-- # Final answer- lm += "\nFinal Answer: " + gen("answer", max_tokens=100)- return lm-```--## Backend Configuration--### OpenAI (remote — unconstrained only)--> Remote API backends cannot do constrained generation (regex/select/grammar);-> use them only for plain chat/`gen()`. For constraints, use a local backend.--```python-from guidance import models--lm = models.OpenAI(- model="gpt-4o-mini",- api_key="your-api-key" # Or set OPENAI_API_KEY env var-)-```--### Local Models (Transformers)--```python-from guidance.models import Transformers--lm = Transformers(- "microsoft/Phi-4-mini-instruct",- device="cuda" # Or "cpu"-)-```--### Local Models (llama.cpp)--```python-from guidance.models import LlamaCpp--lm = LlamaCpp(- model_path="/path/to/model.gguf",- n_ctx=4096,- n_gpu_layers=35-)-```--## Common Patterns--### Pattern 1: JSON Generation--```python-from guidance import models, gen, system, user, assistant--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--with system():- lm += "You generate valid JSON."--with user():- lm += "Generate a user profile with name, age, and email."--with assistant():- lm += """{- "name": """ + gen("name", regex=r'"[A-Za-z ]+"', max_tokens=30) + """,- "age": """ + gen("age", regex=r"[0-9]+", max_tokens=3) + """,- "email": """ + gen("email", regex=r'"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"', max_tokens=50) + """-}"""--print(lm) # Valid JSON guaranteed-```--### Pattern 2: Classification--```python-from guidance import models, gen, select--lm = models.Transformers("microsoft/Phi-4-mini-instruct")--text = "This product is amazing! I love it."--lm += f"Text: {text}\n"-lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")-lm += "\nConfidence: " + gen("confidence", regex=r"[0-9]+", max_tokens=3) + "%"--print(f"Sentiment: {lm['sentiment']}")-print(f"Confidence: {lm['confidence']}%")-```--### Pattern 3: Multi-Step Reasoning--```python-from guidance import models, gen, guidance--@guidance-def chain_of_thought(lm, question):- """Generate answer with step-by-step reasoning."""- lm += f"Question: {question}\n\n"-- # Generate multiple reasoning steps- for i in range(3):- lm += f"Step {i+1}: " + gen(f"step_{i+1}", stop="\n", max_tokens=100) + "\n"-- # Final answer- lm += "\nTherefore, the answer is: " + gen("answer", max_tokens=50)-- return lm--lm = models.Transformers("microsoft/Phi-4-mini-instruct")-lm = chain_of_thought(lm, "What is 15% of 200?")--print(lm["answer"])-```--### Pattern 4: ReAct Agent--```python-from guidance import models, gen, select, guidance--@guidance(stateless=False)-def react_agent(lm, question):- """ReAct agent with tool use."""- tools = {- "calculator": lambda expr: eval(expr),- "search": lambda query: f"Search results for: {query}",- }-- lm += f"Question: {question}\n\n"-- for round in range(5):- # Thought- lm += f"Thought: " + gen("thought", stop="\n") + "\n"-- # Action selection- lm += "Action: " + select(["calculator", "search", "answer"], name="action")-- if lm["action"] == "answer":- lm += "\nFinal Answer: " + gen("answer", max_tokens=100)- break-- # Action input- lm += "\nAction Input: " + gen("action_input", stop="\n") + "\n"-- # Execute tool- if lm["action"] in tools:- result = tools[lm["action"]](lm["action_input"])- lm += f"Observation: {result}\n\n"-- return lm--lm = models.Transformers("microsoft/Phi-4-mini-instruct")-lm = react_agent(lm, "What is 25 * 4 + 10?")-print(lm["answer"])-```--### Pattern 5: Data Extraction--```python-from guidance import models, gen, guidance--@guidance-def extract_entities(lm, text):- """Extract structured entities from text."""- lm += f"Text: {text}\n\n"-- # Extract person- lm += "Person: " + gen("person", stop="\n", max_tokens=30) + "\n"-- # Extract organization- lm += "Organization: " + gen("organization", stop="\n", max_tokens=30) + "\n"-- # Extract date- lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}", max_tokens=10) + "\n"-- # Extract location- lm += "Location: " + gen("location", stop="\n", max_tokens=30) + "\n"-- return lm--text = "Tim Cook announced at Apple Park on 2024-09-15 in Cupertino."--lm = models.Transformers("microsoft/Phi-4-mini-instruct")-lm = extract_entities(lm, text)--print(f"Person: {lm['person']}")-print(f"Organization: {lm['organization']}")-print(f"Date: {lm['date']}")-print(f"Location: {lm['location']}")-```--## Best Practices--### 1. Use Regex for Format Validation--```python-# ✅ Good: Regex ensures valid format-lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")--# ❌ Bad: Free generation may produce invalid emails-lm += "Email: " + gen("email", max_tokens=50)-```--### 2. Use select() for Fixed Categories--```python-# ✅ Good: Guaranteed valid category-lm += "Status: " + select(["pending", "approved", "rejected"], name="status")--# ❌ Bad: May generate typos or invalid values-lm += "Status: " + gen("status", max_tokens=20)-```--### 3. Leverage Token Healing--```python-# Token healing is enabled by default-# No special action needed - just concatenate naturally-lm += "The capital is " + gen("capital") # Automatic healing-```--### 4. Use stop Sequences--```python-# ✅ Good: Stop at newline for single-line outputs-lm += "Name: " + gen("name", stop="\n")--# ❌ Bad: May generate multiple lines-lm += "Name: " + gen("name", max_tokens=50)-```--### 5. Create Reusable Functions--```python-# ✅ Good: Reusable pattern-@guidance-def generate_person(lm):- lm += "Name: " + gen("name", stop="\n")- lm += "\nAge: " + gen("age", regex=r"[0-9]+")- return lm--# Use multiple times-lm = generate_person(lm)-lm += "\n\n"-lm = generate_person(lm)-```--### 6. Balance Constraints--```python-# ✅ Good: Reasonable constraints-lm += gen("name", regex=r"[A-Za-z ]+", max_tokens=30)--# ❌ Too strict: May fail or be very slow-lm += gen("name", regex=r"^(John|Jane)$", max_tokens=10)-```--## Comparison to Alternatives--| Feature | Guidance | Instructor | Outlines | LMQL |-|---------|----------|------------|----------|------|-| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |-| Grammar Support | ✅ CFG | ❌ No | ✅ CFG | ✅ CFG |-| Pydantic Validation | ❌ No | ✅ Yes | ✅ Yes | ❌ No |-| Token Healing | ✅ Yes | ❌ No | ✅ Yes | ❌ No |-| Local Models | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |-| API Models | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |-| Pythonic Syntax | ✅ Yes | ✅ Yes | ✅ Yes | ❌ SQL-like |-| Learning Curve | Low | Low | Medium | High |--**When to choose Guidance:**-- Need regex/grammar constraints-- Want token healing-- Building complex workflows with control flow-- Using local models (Transformers, llama.cpp)-- Prefer Pythonic syntax--**When to choose alternatives:**-- Instructor: Need Pydantic validation with automatic retrying-- Outlines: Need JSON schema validation-- LMQL: Prefer declarative query syntax--## Performance Characteristics--**Latency Reduction:**-- 30-50% faster than traditional prompting for constrained outputs-- Token healing reduces unnecessary regeneration-- Grammar constraints prevent invalid token generation--**Memory Usage:**-- Minimal overhead vs unconstrained generation-- Grammar compilation cached after first use-- Efficient token filtering at inference time--**Token Efficiency:**-- Prevents wasted tokens on invalid outputs-- No need for retry loops-- Direct path to valid outputs--## Resources--- **Documentation**: https://guidance.readthedocs.io-- **GitHub**: https://github.com/guidance-ai/guidance (18k+ stars)-- **Notebooks**: https://github.com/guidance-ai/guidance/tree/main/notebooks-- **Discord**: Community support available--## See Also--- `references/constraints.md` - Comprehensive regex and grammar patterns-- `references/backends.md` - Backend-specific configuration-- `references/examples.md` - Production-ready examplesdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md b/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.mddeleted file mode 100644index 723cf707a7f..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md+++ /dev/null@@ -1,535 +0,0 @@-----title: "Huggingface Tokenizers — Fast BPE/WordPiece tokenization and custom vocab training"-sidebar_label: "Huggingface Tokenizers"-description: "Fast BPE/WordPiece tokenization and custom vocab training"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Huggingface Tokenizers--Fast BPE/WordPiece tokenization and custom vocab training.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/huggingface-tokenizers` |-| Path | `optional-skills/mlops/huggingface-tokenizers` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `tokenizers`, `transformers`, `datasets` |-| Platforms | linux, macos, windows |-| Tags | `Tokenization`, `HuggingFace`, `BPE`, `WordPiece`, `Unigram`, `Fast Tokenization`, `Rust`, `Custom Tokenizer`, `Alignment Tracking`, `Production` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# HuggingFace Tokenizers - Fast Tokenization for NLP--Fast, production-ready tokenizers with Rust performance and Python ease-of-use.--## When to use HuggingFace Tokenizers--**Use HuggingFace Tokenizers when:**-- Need extremely fast tokenization (<20s per GB of text)-- Training custom tokenizers from scratch-- Want alignment tracking (token → original text position)-- Building production NLP pipelines-- Need to tokenize large corpora efficiently--**Performance**:-- **Speed**: <20 seconds to tokenize 1GB on CPU-- **Implementation**: Rust core with Python/Node.js bindings-- **Efficiency**: 10-100× faster than pure Python implementations--**Use alternatives instead**:-- **SentencePiece**: Language-independent, used by T5/ALBERT-- **tiktoken**: OpenAI's BPE tokenizer for GPT models-- **transformers AutoTokenizer**: Loading pretrained only (uses this library internally)--## Quick start--### Installation--```bash-# Install tokenizers-pip install tokenizers--# With transformers integration-pip install tokenizers transformers-```--### Load pretrained tokenizer--```python-from tokenizers import Tokenizer--# Load from HuggingFace Hub-tokenizer = Tokenizer.from_pretrained("bert-base-uncased")--# Encode text-output = tokenizer.encode("Hello, how are you?")-print(output.tokens) # ['hello', ',', 'how', 'are', 'you', '?']-print(output.ids) # [7592, 1010, 2129, 2024, 2017, 1029]--# Decode back-text = tokenizer.decode(output.ids)-print(text) # "hello, how are you?"-```--### Train custom BPE tokenizer--```python-from tokenizers import Tokenizer-from tokenizers.models import BPE-from tokenizers.trainers import BpeTrainer-from tokenizers.pre_tokenizers import Whitespace--# Initialize tokenizer with BPE model-tokenizer = Tokenizer(BPE(unk_token="[UNK]"))-tokenizer.pre_tokenizer = Whitespace()--# Configure trainer-trainer = BpeTrainer(- vocab_size=30000,- special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],- min_frequency=2-)--# Train on files-files = ["train.txt", "validation.txt"]-tokenizer.train(files, trainer)--# Save-tokenizer.save("my-tokenizer.json")-```--**Training time**: ~1-2 minutes for 100MB corpus, ~10-20 minutes for 1GB--### Batch encoding with padding--```python-# Enable padding-tokenizer.enable_padding(pad_id=3, pad_token="[PAD]")--# Encode batch-texts = ["Hello world", "This is a longer sentence"]-encodings = tokenizer.encode_batch(texts)--for encoding in encodings:- print(encoding.ids)-# [101, 7592, 2088, 102, 3, 3, 3]-# [101, 2023, 2003, 1037, 2936, 6251, 102]-```--## Tokenization algorithms--### BPE (Byte-Pair Encoding)--**How it works**:-1. Start with character-level vocabulary-2. Find most frequent character pair-3. Merge into new token, add to vocabulary-4. Repeat until vocabulary size reached--**Used by**: GPT-2, GPT-3, RoBERTa, BART, DeBERTa--```python-from tokenizers import Tokenizer-from tokenizers.models import BPE-from tokenizers.trainers import BpeTrainer-from tokenizers.pre_tokenizers import ByteLevel--tokenizer = Tokenizer(BPE(unk_token="<|endoftext|>"))-tokenizer.pre_tokenizer = ByteLevel()--trainer = BpeTrainer(- vocab_size=50257,- special_tokens=["<|endoftext|>"],- min_frequency=2-)--tokenizer.train(files=["data.txt"], trainer=trainer)-```--**Advantages**:-- Handles OOV words well (breaks into subwords)-- Flexible vocabulary size-- Good for morphologically rich languages--**Trade-offs**:-- Tokenization depends on merge order-- May split common words unexpectedly--### WordPiece--**How it works**:-1. Start with character vocabulary-2. Score merge pairs: `frequency(pair) / (frequency(first) × frequency(second))`-3. Merge highest scoring pair-4. Repeat until vocabulary size reached--**Used by**: BERT, DistilBERT, MobileBERT--```python-from tokenizers import Tokenizer-from tokenizers.models import WordPiece-from tokenizers.trainers import WordPieceTrainer-from tokenizers.pre_tokenizers import Whitespace-from tokenizers.normalizers import BertNormalizer--tokenizer = Tokenizer(WordPiece(unk_token="[UNK]"))-tokenizer.normalizer = BertNormalizer(lowercase=True)-tokenizer.pre_tokenizer = Whitespace()--trainer = WordPieceTrainer(- vocab_size=30522,- special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],- continuing_subword_prefix="##"-)--tokenizer.train(files=["corpus.txt"], trainer=trainer)-```--**Advantages**:-- Prioritizes meaningful merges (high score = semantically related)-- Used successfully in BERT (state-of-the-art results)--**Trade-offs**:-- Unknown words become `[UNK]` if no subword match-- Saves vocabulary, not merge rules (larger files)--### Unigram--**How it works**:-1. Start with large vocabulary (all substrings)-2. Compute loss for corpus with current vocabulary-3. Remove tokens with minimal impact on loss-4. Repeat until vocabulary size reached--**Used by**: ALBERT, T5, mBART, XLNet (via SentencePiece)--```python-from tokenizers import Tokenizer-from tokenizers.models import Unigram-from tokenizers.trainers import UnigramTrainer--tokenizer = Tokenizer(Unigram())--trainer = UnigramTrainer(- vocab_size=8000,- special_tokens=["<unk>", "<s>", "</s>"],- unk_token="<unk>"-)--tokenizer.train(files=["data.txt"], trainer=trainer)-```--**Advantages**:-- Probabilistic (finds most likely tokenization)-- Works well for languages without word boundaries-- Handles diverse linguistic contexts--**Trade-offs**:-- Computationally expensive to train-- More hyperparameters to tune--## Tokenization pipeline--Complete pipeline: **Normalization → Pre-tokenization → Model → Post-processing**--### Normalization--Clean and standardize text:--```python-from tokenizers.normalizers import NFD, StripAccents, Lowercase, Sequence--tokenizer.normalizer = Sequence([- NFD(), # Unicode normalization (decompose)- Lowercase(), # Convert to lowercase- StripAccents() # Remove accents-])--# Input: "Héllo WORLD"-# After normalization: "hello world"-```--**Common normalizers**:-- `NFD`, `NFC`, `NFKD`, `NFKC` - Unicode normalization forms-- `Lowercase()` - Convert to lowercase-- `StripAccents()` - Remove accents (é → e)-- `Strip()` - Remove whitespace-- `Replace(pattern, content)` - Regex replacement--### Pre-tokenization--Split text into word-like units:--```python-from tokenizers.pre_tokenizers import Whitespace, Punctuation, Sequence, ByteLevel--# Split on whitespace and punctuation-tokenizer.pre_tokenizer = Sequence([- Whitespace(),- Punctuation()-])--# Input: "Hello, world!"-# After pre-tokenization: ["Hello", ",", "world", "!"]-```--**Common pre-tokenizers**:-- `Whitespace()` - Split on spaces, tabs, newlines-- `ByteLevel()` - GPT-2 style byte-level splitting-- `Punctuation()` - Isolate punctuation-- `Digits(individual_digits=True)` - Split digits individually-- `Metaspace()` - Replace spaces with ▁ (SentencePiece style)--### Post-processing--Add special tokens for model input:--```python-from tokenizers.processors import TemplateProcessing--# BERT-style: [CLS] sentence [SEP]-tokenizer.post_processor = TemplateProcessing(- single="[CLS] $A [SEP]",- pair="[CLS] $A [SEP] $B [SEP]",- special_tokens=[- ("[CLS]", 1),- ("[SEP]", 2),- ],-)-```--**Common patterns**:-```python-# GPT-2: sentence <|endoftext|>-TemplateProcessing(- single="$A <|endoftext|>",- special_tokens=[("<|endoftext|>", 50256)]-)--# RoBERTa: <s> sentence </s>-TemplateProcessing(- single="<s> $A </s>",- pair="<s> $A </s> </s> $B </s>",- special_tokens=[("<s>", 0), ("</s>", 2)]-)-```--## Alignment tracking--Track token positions in original text:--```python-output = tokenizer.encode("Hello, world!")--# Get token offsets-for token, offset in zip(output.tokens, output.offsets):- start, end = offset- print(f"{token:10} → [{start:2}, {end:2}): {text[start:end]!r}")--# Output:-# hello → [ 0, 5): 'Hello'-# , → [ 5, 6): ','-# world → [ 7, 12): 'world'-# ! → [12, 13): '!'-```--**Use cases**:-- Named entity recognition (map predictions back to text)-- Question answering (extract answer spans)-- Token classification (align labels to original positions)--## Integration with transformers--### Load with AutoTokenizer--```python-from transformers import AutoTokenizer--# AutoTokenizer automatically uses fast tokenizers-tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")--# Check if using fast tokenizer-print(tokenizer.is_fast) # True--# Access underlying tokenizers.Tokenizer-fast_tokenizer = tokenizer.backend_tokenizer-print(type(fast_tokenizer)) # <class 'tokenizers.Tokenizer'>-```--### Convert custom tokenizer to transformers--```python-from tokenizers import Tokenizer-from transformers import PreTrainedTokenizerFast--# Train custom tokenizer-tokenizer = Tokenizer(BPE())-# ... train tokenizer ...-tokenizer.save("my-tokenizer.json")--# Wrap for transformers-transformers_tokenizer = PreTrainedTokenizerFast(- tokenizer_file="my-tokenizer.json",- unk_token="[UNK]",- pad_token="[PAD]",- cls_token="[CLS]",- sep_token="[SEP]",- mask_token="[MASK]"-)--# Use like any transformers tokenizer-outputs = transformers_tokenizer(- "Hello world",- padding=True,- truncation=True,- max_length=512,- return_tensors="pt"-)-```--## Common patterns--### Train from iterator (large datasets)--```python-from datasets import load_dataset--# Load dataset-dataset = load_dataset("wikitext", "wikitext-103-raw-v1", split="train")--# Create batch iterator-def batch_iterator(batch_size=1000):- for i in range(0, len(dataset), batch_size):- yield dataset[i:i + batch_size]["text"]--# Train tokenizer-tokenizer.train_from_iterator(- batch_iterator(),- trainer=trainer,- length=len(dataset) # For progress bar-)-```--**Performance**: Processes 1GB in ~10-20 minutes--### Enable truncation and padding--```python-# Enable truncation-tokenizer.enable_truncation(max_length=512)--# Enable padding-tokenizer.enable_padding(- pad_id=tokenizer.token_to_id("[PAD]"),- pad_token="[PAD]",- length=512 # Fixed length, or None for batch max-)--# Encode with both-output = tokenizer.encode("This is a long sentence that will be truncated...")-print(len(output.ids)) # 512-```--### Multi-processing--```python-from tokenizers import Tokenizer-from multiprocessing import Pool--# Load tokenizer-tokenizer = Tokenizer.from_file("tokenizer.json")--def encode_batch(texts):- return tokenizer.encode_batch(texts)--# Process large corpus in parallel-with Pool(8) as pool:- # Split corpus into chunks- chunk_size = 1000- chunks = [corpus[i:i+chunk_size] for i in range(0, len(corpus), chunk_size)]-- # Encode in parallel- results = pool.map(encode_batch, chunks)-```--**Speedup**: 5-8× with 8 cores--## Performance benchmarks--### Training speed--| Corpus Size | BPE (30k vocab) | WordPiece (30k) | Unigram (8k) |-|-------------|-----------------|-----------------|--------------|-| 10 MB | 15 sec | 18 sec | 25 sec |-| 100 MB | 1.5 min | 2 min | 4 min |-| 1 GB | 15 min | 20 min | 40 min |--**Hardware**: 16-core CPU, tested on English Wikipedia--### Tokenization speed--| Implementation | 1 GB corpus | Throughput |-|----------------|-------------|---------------|-| Pure Python | ~20 minutes | ~50 MB/min |-| HF Tokenizers | ~15 seconds | ~4 GB/min |-| **Speedup** | **80×** | **80×** |--**Test**: English text, average sentence length 20 words--### Memory usage--| Task | Memory |-|-------------------------|---------|-| Load tokenizer | ~10 MB |-| Train BPE (30k vocab) | ~200 MB |-| Encode 1M sentences | ~500 MB |--## Supported models--Pre-trained tokenizers available via `from_pretrained()`:--**BERT family**:-- `bert-base-uncased`, `bert-large-cased`-- `distilbert-base-uncased`-- `roberta-base`, `roberta-large`--**GPT family**:-- `gpt2`, `gpt2-medium`, `gpt2-large`-- `distilgpt2`--**T5 family**:-- `t5-small`, `t5-base`, `t5-large`-- `google/flan-t5-xxl`--**Other**:-- `facebook/bart-base`, `facebook/mbart-large-cc25`-- `albert-base-v2`, `albert-xlarge-v2`-- `xlm-roberta-base`, `xlm-roberta-large`--Browse all: https://huggingface.co/models?library=tokenizers--## References--- **[Training Guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/training.md)** - Train custom tokenizers, configure trainers, handle large datasets-- **[Algorithms Deep Dive](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/algorithms.md)** - BPE, WordPiece, Unigram explained in detail-- **[Pipeline Components](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/pipeline.md)** - Normalizers, pre-tokenizers, post-processors, decoders-- **[Transformers Integration](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/integration.md)** - AutoTokenizer, PreTrainedTokenizerFast, special tokens--## Resources--- **Docs**: https://huggingface.co/docs/tokenizers-- **GitHub**: https://github.com/huggingface/tokenizers ⭐ 9,000+-- **Version**: 0.20.0+-- **Course**: https://huggingface.co/learn/nlp-course/chapter6/1-- **Paper**: BPE (Sennrich et al., 2016), WordPiece (Schuster & Nakajima, 2012)diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-inference-outlines.md b/website/docs/user-guide/skills/optional/mlops/mlops-inference-outlines.mddeleted file mode 100644index 6e247586b9e..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-inference-outlines.md+++ /dev/null@@ -1,679 +0,0 @@-----title: "Outlines — Outlines: structured JSON/regex/Pydantic LLM generation"-sidebar_label: "Outlines"-description: "Outlines: structured JSON/regex/Pydantic LLM generation"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Outlines--Outlines: structured JSON/regex/Pydantic LLM generation.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/outlines` |-| Path | `optional-skills/mlops/inference/outlines` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `outlines`, `transformers`, `vllm`, `pydantic` |-| Platforms | linux, macos, windows |-| Tags | `Prompt Engineering`, `Outlines`, `Structured Generation`, `JSON Schema`, `Pydantic`, `Local Models`, `Grammar-Based Generation`, `vLLM`, `Transformers`, `Type Safety` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Outlines: Structured Text Generation--## When to Use This Skill--Use Outlines when you need to:-- **Guarantee valid JSON/XML/code** structure during generation-- **Use Pydantic models** for type-safe outputs-- **Support local models** (Transformers, llama.cpp, vLLM)-- **Maximize inference speed** with zero-overhead structured generation-- **Generate against JSON schemas** automatically-- **Control token sampling** at the grammar level--**GitHub Stars**: 12,000+ | **From**: dottxt.ai (formerly .txt)--> **API note (Outlines 1.x):** This skill targets the current v1 API.-> The pre-1.0 helpers (`outlines.models.transformers(...)`,-> `outlines.generate.json/choice/regex/...`) have been **removed**. In v1 you-> create a model with `outlines.from_transformers(...)` (or `from_vllm`,-> `from_llamacpp`, `from_openai`) and then **call the model directly** with an-> output type: `model(prompt, output_type)`. JSON/Pydantic outputs are returned-> as a **JSON string** — validate with `YourModel.model_validate_json(result)`.--## Installation--```bash-# Base installation-pip install outlines--# With specific backends-pip install outlines transformers # Hugging Face models-pip install outlines llama-cpp-python # llama.cpp-pip install outlines vllm # vLLM for high-throughput-```--## Quick Start--### Basic Example: Classification--```python-import outlines-from typing import Literal-from transformers import AutoModelForCausalLM, AutoTokenizer--MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"--# v1: wrap a Transformers model + tokenizer-model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),- AutoTokenizer.from_pretrained(MODEL_NAME),-)--# Call the model directly with an output type-prompt = "Sentiment of 'This product is amazing!': "-sentiment = model(prompt, Literal["positive", "negative", "neutral"])--print(sentiment) # "positive" (guaranteed one of these)-```--### With Pydantic Models--```python-from pydantic import BaseModel-import outlines-from transformers import AutoModelForCausalLM, AutoTokenizer--class User(BaseModel):- name: str- age: int- email: str--MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"-model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),- AutoTokenizer.from_pretrained(MODEL_NAME),-)--# Generate structured output (returns a JSON string)-prompt = "Extract user: John Doe, 30 years old, [email protected]"-result = model(prompt, User, max_new_tokens=200)--user = User.model_validate_json(result) # parse into the Pydantic model-print(user.name) # "John Doe"-print(user.age) # 30-print(user.email) # "[email protected]"-```--## Core Concepts--### 1. Constrained Token Sampling--Outlines constrains token generation at the logit level using a compiled-automaton derived from your output type.--**How it works:**-1. Convert the output type (JSON/Pydantic/regex/`Literal`) to a schema/grammar-2. Compile the grammar into a token-level automaton-3. Filter invalid tokens at each step during generation-4. Fast-forward when only one valid token exists--**Benefits:**-- **Zero overhead**: Filtering happens at token level-- **Speed improvement**: Fast-forward through deterministic paths-- **Guaranteed validity**: Invalid outputs impossible--```python-import outlines-from pydantic import BaseModel-from transformers import AutoModelForCausalLM, AutoTokenizer--class Person(BaseModel):- name: str- age: int--model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),- AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),-)--result = model("Generate person: Alice, 25", Person)-person = Person.model_validate_json(result)-```--### 2. Output Types--In v1 you pass the desired **output type** directly as the second argument.--#### Multiple choice (`Literal`)--```python-from typing import Literal--sentiment = model("Review: This is great!", Literal["positive", "negative", "neutral"])-# Result: one of the three choices-```--#### JSON via Pydantic--```python-from pydantic import BaseModel--class Product(BaseModel):- name: str- price: float- in_stock: bool--result = model("Extract: iPhone 15, $999, available", Product)-product = Product.model_validate_json(result) # valid Product instance-```--#### Regex (pass a regex string)--```python-# Generate text matching a regex pattern-phone = model("Generate phone number:", r"[0-9]{3}-[0-9]{3}-[0-9]{4}")-# Result: "555-123-4567" (guaranteed to match the pattern)-```--#### Numeric types--```python-# Pass the Python type directly-age = model("Person's age:", int) # guaranteed integer-price = model("Product price:", float) # guaranteed float-```--### 3. Model Backends--Outlines supports multiple local and API-based backends via `from_*` factories.--#### Transformers (Hugging Face)--```python-import outlines-from transformers import AutoModelForCausalLM, AutoTokenizer--model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),- AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),-)--result = model(prompt, YourModel)-```--#### llama.cpp--```python-import outlines-from llama_cpp import Llama--llm = Llama("./models/llama-3.1-8b-instruct.Q4_K_M.gguf", n_gpu_layers=35, n_ctx=4096)-model = outlines.from_llamacpp(llm)--result = model(prompt, YourModel)-```--#### vLLM (High Throughput)--```python-import outlines-from vllm import LLM--llm = LLM("meta-llama/Llama-3.1-8B-Instruct", tensor_parallel_size=2)-model = outlines.from_vllm(llm)--result = model(prompt, YourModel)-```--#### OpenAI (server-side constrained JSON)--```python-import outlines-from openai import OpenAI--client = OpenAI()-model = outlines.from_openai(client, "gpt-4o-mini")--# API backends support JSON-schema style structured output-result = model(prompt, YourModel)-```--### 4. Pydantic Integration--Outlines has first-class Pydantic support with automatic schema translation.-Generation returns a JSON string; call `model_validate_json` to get an instance.--#### Basic Models--```python-from pydantic import BaseModel, Field--class Article(BaseModel):- title: str = Field(description="Article title")- author: str = Field(description="Author name")- word_count: int = Field(description="Number of words", gt=0)- tags: list[str] = Field(description="List of tags")--result = model("Generate article about AI", Article, max_new_tokens=300)-article = Article.model_validate_json(result)-print(article.title)-print(article.word_count) # Guaranteed > 0-```--#### Nested Models--```python-class Address(BaseModel):- street: str- city: str- country: str--class Person(BaseModel):- name: str- age: int- address: Address # Nested model--result = model("Generate person in New York", Person)-person = Person.model_validate_json(result)-print(person.address.city) # "New York"-```--#### Enums and Literals--```python-from enum import Enum-from typing import Literal--class Status(str, Enum):- PENDING = "pending"- APPROVED = "approved"- REJECTED = "rejected"--class Application(BaseModel):- applicant: str- status: Status # Must be one of enum values- priority: Literal["low", "medium", "high"] # Must be one of literals--result = model("Generate application", Application)-app = Application.model_validate_json(result)-print(app.status) # Status.PENDING (or APPROVED/REJECTED)-```--## Common Patterns--### Pattern 1: Data Extraction--```python-from pydantic import BaseModel-import outlines-from transformers import AutoModelForCausalLM, AutoTokenizer--class CompanyInfo(BaseModel):- name: str- founded_year: int- industry: str- employees: int--model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),- AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),-)--text = """-Apple Inc. was founded in 1976 in the technology industry.-The company employs approximately 164,000 people worldwide.-"""--prompt = f"Extract company information:\n{text}\n\nCompany:"-company = CompanyInfo.model_validate_json(model(prompt, CompanyInfo, max_new_tokens=200))--print(f"Name: {company.name}")-print(f"Founded: {company.founded_year}")-print(f"Industry: {company.industry}")-print(f"Employees: {company.employees}")-```--### Pattern 2: Classification--```python-from typing import Literal-from pydantic import BaseModel--# Binary classification-result = model("Email: Buy now! 50% off!", Literal["spam", "not_spam"])--# Multi-class classification-category = model(- "Article: Apple announces new iPhone...",- Literal["technology", "business", "sports", "entertainment"],-)--# With confidence-class Classification(BaseModel):- label: Literal["positive", "negative", "neutral"]- confidence: float--out = model("Review: This product is okay, nothing special", Classification)-result = Classification.model_validate_json(out)-```--### Pattern 3: Structured Forms--```python-class UserProfile(BaseModel):- full_name: str- age: int- email: str- phone: str- country: str- interests: list[str]--prompt = """-Extract user profile from:-Name: Alice Johnson-Age: 28-Email: [email protected]-Phone: 555-0123-Country: USA-Interests: hiking, photography, cooking-"""--profile = UserProfile.model_validate_json(model(prompt, UserProfile, max_new_tokens=250))-print(profile.full_name)-print(profile.interests) # ["hiking", "photography", "cooking"]-```--### Pattern 4: Multi-Entity Extraction--```python-from typing import Literal--class Entity(BaseModel):- name: str- type: Literal["PERSON", "ORGANIZATION", "LOCATION"]--class DocumentEntities(BaseModel):- entities: list[Entity]--text = "Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond."-prompt = f"Extract entities from: {text}"--result = DocumentEntities.model_validate_json(model(prompt, DocumentEntities, max_new_tokens=300))-for entity in result.entities:- print(f"{entity.name} ({entity.type})")-```--### Pattern 5: Code Generation--```python-class PythonFunction(BaseModel):- function_name: str- parameters: list[str]- docstring: str- body: str--prompt = "Generate a Python function to calculate factorial"-func = PythonFunction.model_validate_json(model(prompt, PythonFunction, max_new_tokens=300))--print(f"def {func.function_name}({', '.join(func.parameters)}):")-print(f' """{func.docstring}"""')-print(f" {func.body}")-```--### Pattern 6: Batch Processing--```python-import outlines-from transformers import AutoModelForCausalLM, AutoTokenizer-from pydantic import BaseModel--class Person(BaseModel):- name: str- age: int--model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct", device_map="auto"),- AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),-)--texts = [- "John is 30 years old",- "Alice is 25 years old",- "Bob is 40 years old",-]--# v1 accepts a list of prompts for batched generation-prompts = [f"Extract from: {t}" for t in texts]-outputs = model(prompts, Person, max_new_tokens=100)-people = [Person.model_validate_json(o) for o in outputs]-for person in people:- print(f"{person.name}: {person.age}")-```--## Backend Configuration--### Transformers--```python-import outlines-from transformers import AutoModelForCausalLM, AutoTokenizer--MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"--# Basic usage-model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="auto"),- AutoTokenizer.from_pretrained(MODEL_NAME),-)--# GPU + dtype configuration is set on the HF model itself-import torch-model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map="cuda", torch_dtype=torch.float16),- AutoTokenizer.from_pretrained(MODEL_NAME),-)--# Popular models-for name in [- "meta-llama/Llama-3.1-8B-Instruct",- "mistralai/Mistral-7B-Instruct-v0.3",- "Qwen/Qwen2.5-7B-Instruct",-]:- model = outlines.from_transformers(- AutoModelForCausalLM.from_pretrained(name, device_map="auto"),- AutoTokenizer.from_pretrained(name),- )-```--### llama.cpp--```python-import outlines-from llama_cpp import Llama--# Load GGUF model-llm = Llama(- "./models/llama-3.1-8b.Q4_K_M.gguf",- n_ctx=4096, # Context window- n_gpu_layers=35, # GPU layers- n_threads=8, # CPU threads-)-model = outlines.from_llamacpp(llm)--# Full GPU offload: set n_gpu_layers=-1 on the Llama object-```--### vLLM (Production)--```python-import outlines-from vllm import LLM--# Single GPU-model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-8B-Instruct"))--# Multi-GPU-model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-70B-Instruct", tensor_parallel_size=4))--# With quantization-model = outlines.from_vllm(LLM("meta-llama/Llama-3.1-8B-Instruct", quantization="awq"))-```--## Best Practices--### 1. Use Specific Types--```python-# ✅ Good: Specific types-class Product(BaseModel):- name: str- price: float # Not str- quantity: int # Not str- in_stock: bool # Not str--# ❌ Bad: Everything as string-class Product(BaseModel):- name: str- price: str # Should be float- quantity: str # Should be int-```--### 2. Add Constraints--```python-from pydantic import Field--# ✅ Good: With constraints-class User(BaseModel):- name: str = Field(min_length=1, max_length=100)- age: int = Field(ge=0, le=120)- email: str = Field(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")--# ❌ Bad: No constraints-class User(BaseModel):- name: str- age: int- email: str-```--### 3. Use Enums for Categories--```python-# ✅ Good: Enum for fixed set-class Priority(str, Enum):- LOW = "low"- MEDIUM = "medium"- HIGH = "high"--class Task(BaseModel):- title: str- priority: Priority--# ❌ Bad: Free-form string-class Task(BaseModel):- title: str- priority: str # Can be anything-```--### 4. Provide Context in Prompts--```python-# ✅ Good: Clear context-prompt = """-Extract product information from the following text.-Text: iPhone 15 Pro costs $999 and is currently in stock.-Product:-"""--# ❌ Bad: Minimal context-prompt = "iPhone 15 Pro costs $999 and is currently in stock."-```--### 5. Handle Optional Fields--```python-from typing import Optional--# ✅ Good: Optional fields for incomplete data-class Article(BaseModel):- title: str # Required- author: Optional[str] = None # Optional- date: Optional[str] = None # Optional- tags: list[str] = [] # Default empty list--# Can succeed even if author/date missing-```--### 6. Always Validate JSON Output--```python-# v1 returns a JSON string for Pydantic/JSON output types.-result = model(prompt, Article) # str-article = Article.model_validate_json(result) # Article instance-```--## Comparison to Alternatives--| Feature | Outlines | Instructor | Guidance | LMQL |-|---------|----------|------------|----------|------|-| Pydantic Support | ✅ Native | ✅ Native | ✅ Yes | ❌ No |-| JSON Schema | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |-| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |-| Local Models | ✅ Full | ⚠️ Limited | ✅ Full | ✅ Full |-| API Models | ✅ Yes | ✅ Full | ✅ Yes | ✅ Full |-| Zero Overhead | ✅ Yes | ❌ No | ⚠️ Partial | ✅ Yes |-| Automatic Retrying | ❌ No | ✅ Yes | ❌ No | ❌ No |-| Learning Curve | Low | Low | Low | High |--**When to choose Outlines:**-- Using local models (Transformers, llama.cpp, vLLM)-- Need maximum inference speed-- Want Pydantic model support-- Require zero-overhead structured generation-- Control token sampling process--**When to choose alternatives:**-- Instructor: Need API models with automatic retrying-- Guidance: Need token healing and complex workflows-- LMQL: Prefer declarative query syntax--## Performance Characteristics--**Speed:**-- **Zero overhead**: Structured generation as fast as unconstrained-- **Fast-forward optimization**: Skips deterministic tokens-- **1.2-2x faster** than post-generation validation approaches--**Memory:**-- Automaton compiled once per output type (cached)-- Minimal runtime overhead-- Efficient with vLLM for high throughput--**Accuracy:**-- **100% valid outputs** (guaranteed by the constrained automaton)-- No retry loops needed-- Deterministic token filtering--## Resources--- **Documentation**: https://dottxt-ai.github.io/outlines/-- **GitHub**: https://github.com/dottxt-ai/outlines (12k+ stars)-- **Discord**: https://discord.gg/R9DSu34mGd-- **Blog**: https://blog.dottxt.co--## See Also--- `references/json_generation.md` - Comprehensive JSON and Pydantic patterns-- `references/backends.md` - Backend-specific configuration-- `references/examples.md` - Production-ready examplesdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md b/website/docs/user-guide/skills/optional/mlops/mlops-instructor.mddeleted file mode 100644index 323b03847d9..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-instructor.md+++ /dev/null@@ -1,759 +0,0 @@-----title: "Instructor — Structured LLM outputs validated with Pydantic"-sidebar_label: "Instructor"-description: "Structured LLM outputs validated with Pydantic"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Instructor--Structured LLM outputs validated with Pydantic.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/instructor` |-| Path | `optional-skills/mlops/instructor` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `instructor`, `pydantic`, `openai`, `anthropic` |-| Platforms | linux, macos, windows |-| Tags | `Prompt Engineering`, `Instructor`, `Structured Output`, `Pydantic`, `Data Extraction`, `JSON Parsing`, `Type Safety`, `Validation`, `Streaming`, `OpenAI`, `Anthropic` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Instructor: Structured LLM Outputs--## When to Use This Skill--Use Instructor when you need to:-- **Extract structured data** from LLM responses reliably-- **Validate outputs** against Pydantic schemas automatically-- **Retry failed extractions** with automatic error handling-- **Parse complex JSON** with type safety and validation-- **Stream partial results** for real-time processing-- **Support multiple LLM providers** with consistent API--**GitHub Stars**: 15,000+ | **Battle-tested**: 100,000+ developers--## Installation--```bash-# Base installation-pip install instructor--# With specific providers-pip install "instructor[anthropic]" # Anthropic Claude-pip install "instructor[openai]" # OpenAI-pip install "instructor[all]" # All providers-```--## Quick Start--### Basic Example: Extract User Data--```python-import instructor-from pydantic import BaseModel-from anthropic import Anthropic--# Define output structure-class User(BaseModel):- name: str- age: int- email: str--# Create instructor client-client = instructor.from_anthropic(Anthropic())--# Extract structured data-user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "John Doe is 30 years old. His email is [email protected]"- }],- response_model=User-)--print(user.name) # "John Doe"-print(user.age) # 30-print(user.email) # "[email protected]"-```--### With OpenAI--```python-from openai import OpenAI--client = instructor.from_openai(OpenAI())--user = client.chat.completions.create(- model="gpt-4o-mini",- response_model=User,- messages=[{"role": "user", "content": "Extract: Alice, 25, [email protected]"}]-)-```--## Core Concepts--### 1. Response Models (Pydantic)--Response models define the structure and validation rules for LLM outputs.--#### Basic Model--```python-from pydantic import BaseModel, Field--class Article(BaseModel):- title: str = Field(description="Article title")- author: str = Field(description="Author name")- word_count: int = Field(description="Number of words", gt=0)- tags: list[str] = Field(description="List of relevant tags")--article = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Analyze this article: [article text]"- }],- response_model=Article-)-```--**Benefits:**-- Type safety with Python type hints-- Automatic validation (word_count > 0)-- Self-documenting with Field descriptions-- IDE autocomplete support--#### Nested Models--```python-class Address(BaseModel):- street: str- city: str- country: str--class Person(BaseModel):- name: str- age: int- address: Address # Nested model--person = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "John lives at 123 Main St, Boston, USA"- }],- response_model=Person-)--print(person.address.city) # "Boston"-```--#### Optional Fields--```python-from typing import Optional--class Product(BaseModel):- name: str- price: float- discount: Optional[float] = None # Optional- description: str = Field(default="No description") # Default value--# LLM doesn't need to provide discount or description-```--#### Enums for Constraints--```python-from enum import Enum--class Sentiment(str, Enum):- POSITIVE = "positive"- NEGATIVE = "negative"- NEUTRAL = "neutral"--class Review(BaseModel):- text: str- sentiment: Sentiment # Only these 3 values allowed--review = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "This product is amazing!"- }],- response_model=Review-)--print(review.sentiment) # Sentiment.POSITIVE-```--### 2. Validation--Pydantic validates LLM outputs automatically. If validation fails, Instructor retries.--#### Built-in Validators--```python-from pydantic import Field, EmailStr, HttpUrl--class Contact(BaseModel):- name: str = Field(min_length=2, max_length=100)- age: int = Field(ge=0, le=120) # 0 <= age <= 120- email: EmailStr # Validates email format- website: HttpUrl # Validates URL format--# If LLM provides invalid data, Instructor retries automatically-```--#### Custom Validators--```python-from pydantic import field_validator--class Event(BaseModel):- name: str- date: str- attendees: int-- @field_validator('date')- def validate_date(cls, v):- """Ensure date is in YYYY-MM-DD format."""- import re- if not re.match(r'\d{4}-\d{2}-\d{2}', v):- raise ValueError('Date must be YYYY-MM-DD format')- return v-- @field_validator('attendees')- def validate_attendees(cls, v):- """Ensure positive attendees."""- if v < 1:- raise ValueError('Must have at least 1 attendee')- return v-```--#### Model-Level Validation--```python-from pydantic import model_validator--class DateRange(BaseModel):- start_date: str- end_date: str-- @model_validator(mode='after')- def check_dates(self):- """Ensure end_date is after start_date."""- from datetime import datetime- start = datetime.strptime(self.start_date, '%Y-%m-%d')- end = datetime.strptime(self.end_date, '%Y-%m-%d')-- if end < start:- raise ValueError('end_date must be after start_date')- return self-```--### 3. Automatic Retrying--Instructor retries automatically when validation fails, providing error feedback to the LLM.--```python-# Retries up to 3 times if validation fails-user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Extract user from: John, age unknown"- }],- response_model=User,- max_retries=3 # Default is 3-)--# If age can't be extracted, Instructor tells the LLM:-# "Validation error: age - field required"-# LLM tries again with better extraction-```--**How it works:**-1. LLM generates output-2. Pydantic validates-3. If invalid: Error message sent back to LLM-4. LLM tries again with error feedback-5. Repeats up to max_retries--### 4. Streaming--Stream partial results for real-time processing.--#### Streaming Partial Objects--```python-from instructor import Partial--class Story(BaseModel):- title: str- content: str- tags: list[str]--# Stream partial updates as LLM generates-for partial_story in client.messages.create_partial(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Write a short sci-fi story"- }],- response_model=Story-):- print(f"Title: {partial_story.title}")- print(f"Content so far: {partial_story.content[:100]}...")- # Update UI in real-time-```--#### Streaming Iterables--```python-class Task(BaseModel):- title: str- priority: str--# Stream list items as they're generated-tasks = client.messages.create_iterable(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Generate 10 project tasks"- }],- response_model=Task-)--for task in tasks:- print(f"- {task.title} ({task.priority})")- # Process each task as it arrives-```--## Provider Configuration--### Anthropic Claude--```python-import instructor-from anthropic import Anthropic--client = instructor.from_anthropic(- Anthropic(api_key="your-api-key")-)--# Use with Claude models-response = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=YourModel-)-```--### OpenAI--```python-from openai import OpenAI--client = instructor.from_openai(- OpenAI(api_key="your-api-key")-)--response = client.chat.completions.create(- model="gpt-4o-mini",- response_model=YourModel,- messages=[...]-)-```--### Local Models (Ollama)--```python-from openai import OpenAI--# Point to local Ollama server-client = instructor.from_openai(- OpenAI(- base_url="http://localhost:11434/v1",- api_key="ollama" # Required but ignored- ),- mode=instructor.Mode.JSON-)--response = client.chat.completions.create(- model="llama3.1",- response_model=YourModel,- messages=[...]-)-```--## Common Patterns--### Pattern 1: Data Extraction from Text--```python-class CompanyInfo(BaseModel):- name: str- founded_year: int- industry: str- employees: int- headquarters: str--text = """-Tesla, Inc. was founded in 2003. It operates in the automotive and energy-industry with approximately 140,000 employees. The company is headquartered-in Austin, Texas.-"""--company = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract company information from: {text}"- }],- response_model=CompanyInfo-)-```--### Pattern 2: Classification--```python-class Category(str, Enum):- TECHNOLOGY = "technology"- FINANCE = "finance"- HEALTHCARE = "healthcare"- EDUCATION = "education"- OTHER = "other"--class ArticleClassification(BaseModel):- category: Category- confidence: float = Field(ge=0.0, le=1.0)- keywords: list[str]--classification = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Classify this article: [article text]"- }],- response_model=ArticleClassification-)-```--### Pattern 3: Multi-Entity Extraction--```python-class Person(BaseModel):- name: str- role: str--class Organization(BaseModel):- name: str- industry: str--class Entities(BaseModel):- people: list[Person]- organizations: list[Organization]- locations: list[str]--text = "Tim Cook, CEO of Apple, announced at the event in Cupertino..."--entities = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract all entities from: {text}"- }],- response_model=Entities-)--for person in entities.people:- print(f"{person.name} - {person.role}")-```--### Pattern 4: Structured Analysis--```python-class SentimentAnalysis(BaseModel):- overall_sentiment: Sentiment- positive_aspects: list[str]- negative_aspects: list[str]- suggestions: list[str]- score: float = Field(ge=-1.0, le=1.0)--review = "The product works well but setup was confusing..."--analysis = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Analyze this review: {review}"- }],- response_model=SentimentAnalysis-)-```--### Pattern 5: Batch Processing--```python-def extract_person(text: str) -> Person:- return client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract person from: {text}"- }],- response_model=Person- )--texts = [- "John Doe is a 30-year-old engineer",- "Jane Smith, 25, works in marketing",- "Bob Johnson, age 40, software developer"-]--people = [extract_person(text) for text in texts]-```--## Advanced Features--### Union Types--```python-from typing import Union--class TextContent(BaseModel):- type: str = "text"- content: str--class ImageContent(BaseModel):- type: str = "image"- url: HttpUrl- caption: str--class Post(BaseModel):- title: str- content: Union[TextContent, ImageContent] # Either type--# LLM chooses appropriate type based on content-```--### Dynamic Models--```python-from pydantic import create_model--# Create model at runtime-DynamicUser = create_model(- 'User',- name=(str, ...),- age=(int, Field(ge=0)),- email=(EmailStr, ...)-)--user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=DynamicUser-)-```--### Custom Modes--```python-# For providers without native structured outputs-client = instructor.from_anthropic(- Anthropic(),- mode=instructor.Mode.JSON # JSON mode-)--# Available modes:-# - Mode.ANTHROPIC_TOOLS (recommended for Claude)-# - Mode.JSON (fallback)-# - Mode.TOOLS (OpenAI tools)-```--### Context Management--```python-# Single-use client-with instructor.from_anthropic(Anthropic()) as client:- result = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=YourModel- )- # Client closed automatically-```--## Error Handling--### Handling Validation Errors--```python-from pydantic import ValidationError--try:- user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=User,- max_retries=3- )-except ValidationError as e:- print(f"Failed after retries: {e}")- # Handle gracefully--except Exception as e:- print(f"API error: {e}")-```--### Custom Error Messages--```python-class ValidatedUser(BaseModel):- name: str = Field(description="Full name, 2-100 characters")- age: int = Field(description="Age between 0 and 120", ge=0, le=120)- email: EmailStr = Field(description="Valid email address")-- class Config:- # Custom error messages- json_schema_extra = {- "examples": [- {- "name": "John Doe",- "age": 30,- "email": "[email protected]"- }- ]- }-```--## Best Practices--### 1. Clear Field Descriptions--```python-# ❌ Bad: Vague-class Product(BaseModel):- name: str- price: float--# ✅ Good: Descriptive-class Product(BaseModel):- name: str = Field(description="Product name from the text")- price: float = Field(description="Price in USD, without currency symbol")-```--### 2. Use Appropriate Validation--```python-# ✅ Good: Constrain values-class Rating(BaseModel):- score: int = Field(ge=1, le=5, description="Rating from 1 to 5 stars")- review: str = Field(min_length=10, description="Review text, at least 10 chars")-```--### 3. Provide Examples in Prompts--```python-messages = [{- "role": "user",- "content": """Extract person info from: "John, 30, engineer"--Example format:-{- "name": "John Doe",- "age": 30,- "occupation": "engineer"-}"""-}]-```--### 4. Use Enums for Fixed Categories--```python-# ✅ Good: Enum ensures valid values-class Status(str, Enum):- PENDING = "pending"- APPROVED = "approved"- REJECTED = "rejected"--class Application(BaseModel):- status: Status # LLM must choose from enum-```--### 5. Handle Missing Data Gracefully--```python-class PartialData(BaseModel):- required_field: str- optional_field: Optional[str] = None- default_field: str = "default_value"--# LLM only needs to provide required_field-```--## Comparison to Alternatives--| Feature | Instructor | Manual JSON | LangChain | DSPy |-|---------|------------|-------------|-----------|------|-| Type Safety | ✅ Yes | ❌ No | ⚠️ Partial | ✅ Yes |-| Auto Validation | ✅ Yes | ❌ No | ❌ No | ⚠️ Limited |-| Auto Retry | ✅ Yes | ❌ No | ❌ No | ✅ Yes |-| Streaming | ✅ Yes | ❌ No | ✅ Yes | ❌ No |-| Multi-Provider | ✅ Yes | ⚠️ Manual | ✅ Yes | ✅ Yes |-| Learning Curve | Low | Low | Medium | High |--**When to choose Instructor:**-- Need structured, validated outputs-- Want type safety and IDE support-- Require automatic retries-- Building data extraction systems--**When to choose alternatives:**-- DSPy: Need prompt optimization-- LangChain: Building complex chains-- Manual: Simple, one-off extractions--## Resources--- **Documentation**: https://python.useinstructor.com-- **GitHub**: https://github.com/jxnl/instructor (15k+ stars)-- **Cookbook**: https://python.useinstructor.com/examples-- **Discord**: Community support available--## See Also--- `references/validation.md` - Advanced validation patterns-- `references/providers.md` - Provider-specific configuration-- `references/examples.md` - Real-world use casesdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-llava.md b/website/docs/user-guide/skills/optional/mlops/mlops-llava.mddeleted file mode 100644index bd50b50ab43..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-llava.md+++ /dev/null@@ -1,323 +0,0 @@-----title: "Llava — Vision-language chat: VQA, captioning, image dialogue"-sidebar_label: "Llava"-description: "Vision-language chat: VQA, captioning, image dialogue"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Llava--Vision-language chat: VQA, captioning, image dialogue.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/llava` |-| Path | `optional-skills/mlops/llava` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `transformers`, `torch`, `pillow` |-| Platforms | linux, macos, windows |-| Tags | `LLaVA`, `Vision-Language`, `Multimodal`, `Visual Question Answering`, `Image Chat`, `CLIP`, `Vicuna`, `Conversational AI`, `Instruction Tuning`, `VQA` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# LLaVA - Large Language and Vision Assistant--Open-source vision-language model for conversational image understanding.--## When to use LLaVA--**Use when:**-- Building vision-language chatbots-- Visual question answering (VQA)-- Image description and captioning-- Multi-turn image conversations-- Visual instruction following-- Document understanding with images--**Metrics**:-- **23,000+ GitHub stars**-- GPT-4V level capabilities (targeted)-- Apache 2.0 License-- Multiple model sizes (7B-34B params)--**Use alternatives instead**:-- **GPT-4V**: Highest quality, API-based-- **CLIP**: Simple zero-shot classification-- **BLIP-2**: Better for captioning only-- **Flamingo**: Research, not open-source--## Quick start--### Installation--```bash-# Clone repository-git clone https://github.com/haotian-liu/LLaVA-cd LLaVA--# Install-pip install -e .-```--### Basic usage--```python-from llava.model.builder import load_pretrained_model-from llava.mm_utils import get_model_name_from_path, process_images, tokenizer_image_token-from llava.constants import IMAGE_TOKEN_INDEX, DEFAULT_IMAGE_TOKEN-from llava.conversation import conv_templates-from PIL import Image-import torch--# Load model-model_path = "liuhaotian/llava-v1.5-7b"-tokenizer, model, image_processor, context_len = load_pretrained_model(- model_path=model_path,- model_base=None,- model_name=get_model_name_from_path(model_path)-)--# Load image-image = Image.open("image.jpg")-image_tensor = process_images([image], image_processor, model.config)-image_tensor = image_tensor.to(model.device, dtype=torch.float16)--# Create conversation-conv = conv_templates["llava_v1"].copy()-conv.append_message(conv.roles[0], DEFAULT_IMAGE_TOKEN + "\nWhat is in this image?")-conv.append_message(conv.roles[1], None)-prompt = conv.get_prompt()--# Generate response-input_ids = tokenizer_image_token(prompt, tokenizer, IMAGE_TOKEN_INDEX, return_tensors='pt').unsqueeze(0).to(model.device)--with torch.inference_mode():- output_ids = model.generate(- input_ids,- images=image_tensor,- do_sample=True,- temperature=0.2,- max_new_tokens=512- )--response = tokenizer.decode(output_ids[0], skip_special_tokens=True).strip()-print(response)-```--## Available models--| Model | Parameters | VRAM | Quality |-|-------|------------|------|---------|-| LLaVA-v1.5-7B | 7B | ~14 GB | Good |-| LLaVA-v1.5-13B | 13B | ~28 GB | Better |-| LLaVA-v1.6-34B | 34B | ~70 GB | Best |--```python-# Load different models-model_7b = "liuhaotian/llava-v1.5-7b"-model_13b = "liuhaotian/llava-v1.5-13b"-model_34b = "liuhaotian/llava-v1.6-34b"--# 4-bit quantization for lower VRAM-load_4bit = True # Reduces VRAM by ~4×-```--## CLI usage--```bash-# Single image query-python -m llava.serve.cli \- --model-path liuhaotian/llava-v1.5-7b \- --image-file image.jpg \- --query "What is in this image?"--# Multi-turn conversation-python -m llava.serve.cli \- --model-path liuhaotian/llava-v1.5-7b \- --image-file image.jpg-# Then type questions interactively-```--## Web UI (Gradio)--```bash-# Launch Gradio interface-python -m llava.serve.gradio_web_server \- --model-path liuhaotian/llava-v1.5-7b \- --load-4bit # Optional: reduce VRAM--# Access at http://localhost:7860-```--## Multi-turn conversations--```python-# Initialize conversation-conv = conv_templates["llava_v1"].copy()--# Turn 1-conv.append_message(conv.roles[0], DEFAULT_IMAGE_TOKEN + "\nWhat is in this image?")-conv.append_message(conv.roles[1], None)-response1 = generate(conv, model, image) # "A dog playing in a park"--# Turn 2-conv.messages[-1][1] = response1 # Add previous response-conv.append_message(conv.roles[0], "What breed is the dog?")-conv.append_message(conv.roles[1], None)-response2 = generate(conv, model, image) # "Golden Retriever"--# Turn 3-conv.messages[-1][1] = response2-conv.append_message(conv.roles[0], "What time of day is it?")-conv.append_message(conv.roles[1], None)-response3 = generate(conv, model, image)-```--## Common tasks--### Image captioning--```python-question = "Describe this image in detail."-response = ask(model, image, question)-```--### Visual question answering--```python-question = "How many people are in the image?"-response = ask(model, image, question)-```--### Object detection (textual)--```python-question = "List all the objects you can see in this image."-response = ask(model, image, question)-```--### Scene understanding--```python-question = "What is happening in this scene?"-response = ask(model, image, question)-```--### Document understanding--```python-question = "What is the main topic of this document?"-response = ask(model, document_image, question)-```--## Training custom model--```bash-# Stage 1: Feature alignment (558K image-caption pairs)-bash scripts/v1_5/pretrain.sh--# Stage 2: Visual instruction tuning (150K instruction data)-bash scripts/v1_5/finetune.sh-```--## Quantization (reduce VRAM)--```python-# 4-bit quantization-tokenizer, model, image_processor, context_len = load_pretrained_model(- model_path="liuhaotian/llava-v1.5-13b",- model_base=None,- model_name=get_model_name_from_path("liuhaotian/llava-v1.5-13b"),- load_4bit=True # Reduces VRAM ~4×-)--# 8-bit quantization-load_8bit=True # Reduces VRAM ~2×-```--## Best practices--1. **Start with 7B model** - Good quality, manageable VRAM-2. **Use 4-bit quantization** - Reduces VRAM significantly-3. **GPU required** - CPU inference extremely slow-4. **Clear prompts** - Specific questions get better answers-5. **Multi-turn conversations** - Maintain conversation context-6. **Temperature 0.2-0.7** - Balance creativity/consistency-7. **max_new_tokens 512-1024** - For detailed responses-8. **Batch processing** - Process multiple images sequentially--## Performance--| Model | VRAM (FP16) | VRAM (4-bit) | Speed (tokens/s) |-|-------|-------------|--------------|------------------|-| 7B | ~14 GB | ~4 GB | ~20 |-| 13B | ~28 GB | ~8 GB | ~12 |-| 34B | ~70 GB | ~18 GB | ~5 |--*On A100 GPU*--## Benchmarks--LLaVA achieves competitive scores on:-- **VQAv2**: 78.5%-- **GQA**: 62.0%-- **MM-Vet**: 35.4%-- **MMBench**: 64.3%--## Limitations--1. **Hallucinations** - May describe things not in image-2. **Spatial reasoning** - Struggles with precise locations-3. **Small text** - Difficulty reading fine print-4. **Object counting** - Imprecise for many objects-5. **VRAM requirements** - Need powerful GPU-6. **Inference speed** - Slower than CLIP--## Integration with frameworks--### LangChain--```python-from langchain.llms.base import LLM--class LLaVALLM(LLM):- def _call(self, prompt, stop=None):- # Custom LLaVA inference- return response--llm = LLaVALLM()-```--### Gradio App--```python-import gradio as gr--def chat(image, text, history):- response = ask_llava(model, image, text)- return response--demo = gr.ChatInterface(- chat,- additional_inputs=[gr.Image(type="pil")],- title="LLaVA Chat"-)-demo.launch()-```--## Resources--- **GitHub**: https://github.com/haotian-liu/LLaVA ⭐ 23,000+-- **Paper**: https://arxiv.org/abs/2304.08485-- **Demo**: https://llava.hliu.cc-- **Models**: https://huggingface.co/liuhaotian-- **License**: Apache 2.0diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub.md b/website/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub.mddeleted file mode 100644index ee1cd9e093f..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub.md+++ /dev/null@@ -1,100 +0,0 @@-----title: "Huggingface Hub — HuggingFace hf CLI: search/download/upload models, datasets"-sidebar_label: "Huggingface Hub"-description: "HuggingFace hf CLI: search/download/upload models, datasets"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Huggingface Hub--HuggingFace hf CLI: search/download/upload models, datasets.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/huggingface-hub` |-| Path | `optional-skills/mlops/models/huggingface-hub` |-| Version | `1.0.1` |-| Author | Hugging Face |-| License | MIT |-| Platforms | linux, macos, windows |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Hugging Face CLI (`hf`) Reference Guide--The `hf` command is the modern command-line interface for interacting with the Hugging Face Hub, providing tools to manage repositories, models, datasets, and Spaces.--> **IMPORTANT:** The `hf` command replaces the now deprecated `huggingface-cli` command.--## Quick Start-* **Installation:** `curl -LsSf https://hf.co/cli/install.sh | bash -s`-* **Help:** Use `hf --help` to view all available functions and real-world examples.-* **Authentication:** Recommended via `HF_TOKEN` environment variable or the `--token` flag.-------## Core Commands--### General Operations-* `hf download REPO_ID`: Download files from the Hub.-* `hf upload REPO_ID`: Upload files/folders (recommended for single-commit; also handles resumable uploads of large directories).-* `hf upload-large-folder REPO_ID LOCAL_PATH`: **[Deprecated]** — use `hf upload` instead.-* `hf sync`: Sync files between a local directory and a bucket.-* `hf env` / `hf version`: View environment and version details.--### Authentication (`hf auth`)-* `login` / `logout`: Manage sessions using tokens from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).-* `list` / `switch`: Manage and toggle between multiple stored access tokens.-* `whoami`: Identify the currently logged-in account.--### Repository Management (`hf repos`)-* `create` / `delete`: Create or permanently remove repositories.-* `duplicate`: Clone a model, dataset, or Space to a new ID.-* `move`: Transfer a repository between namespaces.-* `branch` / `tag`: Manage Git-like references.-* `delete-files`: Remove specific files using patterns.-------## Specialized Hub Interactions--### Datasets & Models-* **Datasets:** `hf datasets list`, `info`, and `parquet` (list parquet URLs).-* **SQL Queries:** `hf datasets sql SQL` — Execute raw SQL via DuckDB against dataset parquet URLs.-* **Models:** `hf models list` and `info`.-* **Papers:** `hf papers ls` — View daily papers.--### Discussions & Pull Requests (`hf discussions`)-* Manage the lifecycle of Hub contributions: `list`, `create`, `info`, `comment`, `close`, `reopen`, and `rename`.-* `diff`: View changes in a PR.-* `merge`: Finalize pull requests.--### Infrastructure & Compute-* **Endpoints:** Deploy and manage Inference Endpoints (`deploy`, `pause`, `resume`, `scale-to-zero`, `catalog`).-* **Jobs:** Run compute tasks on HF infrastructure. Includes `hf jobs uv` for running Python scripts with inline dependencies and `stats` for resource monitoring.-* **Spaces:** Manage interactive apps. Includes `dev-mode` and `hot-reload` for Python files without full restarts.--### Storage & Automation-* **Buckets:** Full S3-like bucket management (`create`, `cp`, `mv`, `rm`, `sync`).-* **Cache:** Manage local storage with `list`, `prune` (remove detached revisions), and `verify` (checksum checks).-* **Webhooks:** Automate workflows by managing Hub webhooks (`create`, `watch`, `enable`/`disable`).-* **Collections:** Organize Hub items into collections (`add-item`, `update`, `list`).-------## Advanced Usage & Tips--### Global Flags-* `--format json`: Produces machine-readable output for automation.-* `-q` / `--quiet`: Limits output to IDs only.--### Extensions & Skills-* **Extensions:** Extend CLI functionality via GitHub repositories using `hf extensions install REPO_ID`.-* **Skills:** Manage AI assistant skills with `hf skills add`.diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.mdindex 08d659b0030..198a62da0b3 100644--- a/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md+++ b/website/docs/user-guide/skills/optional/mlops/mlops-obliteratus.md@@ -22,7 +22,7 @@ OBLITERATUS: abliterate LLM refusals (diff-in-means).| Dependencies | `obliteratus`, `torch`, `transformers`, `bitsandbytes`, `accelerate`, `safetensors` || Platforms | linux, macos || Tags | `Abliteration`, `Uncensoring`, `Refusal-Removal`, `LLM`, `Weight-Projection`, `SVD`, `Mechanistic-Interpretability`, `HuggingFace`, `Model-Surgery` |-| Related skills | [`serving-llms-vllm`](../../optional/mlops/mlops-inference-serving-llms-vllm.md), [`llama-cpp`](../../optional/mlops/mlops-inference-llama-cpp.md), [`huggingface-tokenizers`](../../optional/mlops/mlops-huggingface-tokenizers.md) |+| Related skills | [`serving-llms-vllm`](../../optional/mlops/mlops-inference-serving-llms-vllm.md), [`llama-cpp`](../../optional/mlops/mlops-inference-llama-cpp.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-pinecone.md b/website/docs/user-guide/skills/optional/mlops/mlops-pinecone.mddeleted file mode 100644index d9e57578dde..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-pinecone.md+++ /dev/null@@ -1,396 +0,0 @@-----title: "Pinecone — Managed vector DB for production RAG and search"-sidebar_label: "Pinecone"-description: "Managed vector DB for production RAG and search"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Pinecone--Managed vector DB for production RAG and search.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/pinecone` |-| Path | `optional-skills/mlops/pinecone` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `pinecone` |-| Platforms | linux, macos, windows |-| Tags | `RAG`, `Pinecone`, `Vector Database`, `Managed Service`, `Serverless`, `Hybrid Search`, `Production`, `Auto-Scaling`, `Low Latency`, `Recommendations` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Pinecone - Managed Vector Database--The vector database for production AI applications.--## When to use Pinecone--**Use when:**-- Need managed, serverless vector database-- Production RAG applications-- Auto-scaling required-- Low latency critical (<100ms)-- Don't want to manage infrastructure-- Need hybrid search (dense + sparse vectors)--**Metrics**:-- Fully managed SaaS-- Auto-scales to billions of vectors-- **p95 latency <100ms**-- 99.9% uptime SLA--**Use alternatives instead**:-- **Chroma**: Self-hosted, open-source-- **FAISS**: Offline, pure similarity search-- **Weaviate**: Self-hosted with more features--## Quick start--### Installation--```bash-pip install pinecone-```--> Note: the old `pinecone-client` package is deprecated. Install `pinecone` (v5+; current 9.x). The import stays `from pinecone import Pinecone`.--### Basic usage--```python-from pinecone import Pinecone, ServerlessSpec--# Initialize-pc = Pinecone(api_key="your-api-key")--# Create index-pc.create_index(- name="my-index",- dimension=1536, # Must match embedding dimension- metric="cosine", # or "euclidean", "dotproduct"- spec=ServerlessSpec(cloud="aws", region="us-east-1")-)--# Connect to index-index = pc.Index("my-index")--# Upsert vectors-index.upsert(vectors=[- {"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "A"}},- {"id": "vec2", "values": [0.3, 0.4, ...], "metadata": {"category": "B"}}-])--# Query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- include_metadata=True-)--print(results["matches"])-```--## Core operations--### Create index--```python-# Serverless (recommended)-pc.create_index(- name="my-index",- dimension=1536,- metric="cosine",- spec=ServerlessSpec(- cloud="aws", # or "gcp", "azure"- region="us-east-1"- )-)--# Pod-based (for consistent performance)-from pinecone import PodSpec--pc.create_index(- name="my-index",- dimension=1536,- metric="cosine",- spec=PodSpec(- environment="us-east1-gcp",- pod_type="p1.x1"- )-)-```--### Upsert vectors--```python-# Single upsert-index.upsert(vectors=[- {- "id": "doc1",- "values": [0.1, 0.2, ...], # 1536 dimensions- "metadata": {- "text": "Document content",- "category": "tutorial",- "timestamp": "2025-01-01"- }- }-])--# Batch upsert (recommended)-vectors = [- {"id": f"vec{i}", "values": embedding, "metadata": metadata}- for i, (embedding, metadata) in enumerate(zip(embeddings, metadatas))-]--index.upsert(vectors=vectors, batch_size=100)-```--### Query vectors--```python-# Basic query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=10,- include_metadata=True,- include_values=False-)--# With metadata filtering-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- filter={"category": {"$eq": "tutorial"}}-)--# Namespace query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- namespace="production"-)--# Access results-for match in results["matches"]:- print(f"ID: {match['id']}")- print(f"Score: {match['score']}")- print(f"Metadata: {match['metadata']}")-```--### Metadata filtering--```python-# Exact match-filter = {"category": "tutorial"}--# Comparison-filter = {"price": {"$gte": 100}} # $gt, $gte, $lt, $lte, $ne--# Logical operators-filter = {- "$and": [- {"category": "tutorial"},- {"difficulty": {"$lte": 3}}- ]-} # Also: $or--# In operator-filter = {"tags": {"$in": ["python", "ml"]}}-```--## Namespaces--```python-# Partition data by namespace-index.upsert(- vectors=[{"id": "vec1", "values": [...]}],- namespace="user-123"-)--# Query specific namespace-results = index.query(- vector=[...],- namespace="user-123",- top_k=5-)--# List namespaces-stats = index.describe_index_stats()-print(stats['namespaces'])-```--## Hybrid search (dense + sparse)--```python-# Upsert with sparse vectors-index.upsert(vectors=[- {- "id": "doc1",- "values": [0.1, 0.2, ...], # Dense vector- "sparse_values": {- "indices": [10, 45, 123], # Token IDs- "values": [0.5, 0.3, 0.8] # TF-IDF scores- },- "metadata": {"text": "..."}- }-])--# Hybrid query-# NOTE: index.query() does NOT accept an `alpha` kwarg. Pinecone stores a-# single sparse-dense vector, so weighting must be applied by pre-scaling the-# query vectors before sending them. Use the hybrid_score_norm helper below-# (alpha * dense + (1 - alpha) * sparse; alpha=1 → pure dense, 0 → pure sparse).--def hybrid_score_norm(dense, sparse, alpha: float):- """Scale dense/sparse query vectors for weighted hybrid search."""- if not 0 <= alpha <= 1:- raise ValueError("alpha must be between 0 and 1")- scaled_sparse = {- "indices": sparse["indices"],- "values": [v * (1 - alpha) for v in sparse["values"]],- }- return [v * alpha for v in dense], scaled_sparse--hdense, hsparse = hybrid_score_norm(- dense=[0.1, 0.2, ...],- sparse={"indices": [10, 45], "values": [0.5, 0.3]},- alpha=0.5, # 0=sparse, 1=dense, 0.5=balanced-)--results = index.query(- vector=hdense,- sparse_vector=hsparse,- top_k=5,-)-```--## LangChain integration--```python-from langchain_pinecone import PineconeVectorStore-from langchain_openai import OpenAIEmbeddings--# Create vector store-vectorstore = PineconeVectorStore.from_documents(- documents=docs,- embedding=OpenAIEmbeddings(),- index_name="my-index"-)--# Query-results = vectorstore.similarity_search("query", k=5)--# With metadata filter-results = vectorstore.similarity_search(- "query",- k=5,- filter={"category": "tutorial"}-)--# As retriever-retriever = vectorstore.as_retriever(search_kwargs={"k": 10})-```--## LlamaIndex integration--```python-from llama_index.vector_stores.pinecone import PineconeVectorStore--# Connect to Pinecone-pc = Pinecone(api_key="your-key")-pinecone_index = pc.Index("my-index")--# Create vector store-vector_store = PineconeVectorStore(pinecone_index=pinecone_index)--# Use in LlamaIndex-from llama_index.core import StorageContext, VectorStoreIndex--storage_context = StorageContext.from_defaults(vector_store=vector_store)-index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)-```--## Index management--```python-# List indices-indexes = pc.list_indexes()--# Describe index-index_info = pc.describe_index("my-index")-print(index_info)--# Get index stats-stats = index.describe_index_stats()-print(f"Total vectors: {stats['total_vector_count']}")-print(f"Namespaces: {stats['namespaces']}")--# Delete index-pc.delete_index("my-index")-```--## Delete vectors--```python-# Delete by ID-index.delete(ids=["vec1", "vec2"])--# Delete by filter-index.delete(filter={"category": "old"})--# Delete all in namespace-index.delete(delete_all=True, namespace="test")--# Delete entire index-index.delete(delete_all=True)-```--## Best practices--1. **Use serverless** - Auto-scaling, cost-effective-2. **Batch upserts** - More efficient (100-200 per batch)-3. **Add metadata** - Enable filtering-4. **Use namespaces** - Isolate data by user/tenant-5. **Monitor usage** - Check Pinecone dashboard-6. **Optimize filters** - Index frequently filtered fields-7. **Test with free tier** - 1 index, 100K vectors free-8. **Use hybrid search** - Better quality-9. **Set appropriate dimensions** - Match embedding model-10. **Regular backups** - Export important data--## Performance--| Operation | Latency | Notes |-|-----------|---------|-------|-| Upsert | ~50-100ms | Per batch |-| Query (p50) | ~50ms | Depends on index size |-| Query (p95) | ~100ms | SLA target |-| Metadata filter | ~+10-20ms | Additional overhead |--## Pricing (as of 2025)--**Serverless**:-- $0.096 per million read units-- $0.06 per million write units-- $0.06 per GB storage/month--**Free tier**:-- 1 serverless index-- 100K vectors (1536 dimensions)-- Great for prototyping--## Resources--- **Website**: https://www.pinecone.io-- **Docs**: https://docs.pinecone.io-- **Console**: https://app.pinecone.io-- **Pricing**: https://www.pinecone.io/pricingdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md b/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.mddeleted file mode 100644index c1670930930..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-qdrant.md+++ /dev/null@@ -1,522 +0,0 @@-----title: "Qdrant — Vector search engine for production RAG systems"-sidebar_label: "Qdrant"-description: "Vector search engine for production RAG systems"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Qdrant--Vector search engine for production RAG systems.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/qdrant` |-| Path | `optional-skills/mlops/qdrant` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `qdrant-client>=1.14.0` |-| Platforms | linux, macos, windows |-| Tags | `RAG`, `Vector Search`, `Qdrant`, `Semantic Search`, `Embeddings`, `Similarity Search`, `HNSW`, `Production`, `Distributed` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Qdrant - Vector Similarity Search Engine--High-performance vector database written in Rust for production RAG and semantic search.--## When to use Qdrant--**Use Qdrant when:**-- Building production RAG systems requiring low latency-- Need hybrid search (vectors + metadata filtering)-- Require horizontal scaling with sharding/replication-- Want on-premise deployment with full data control-- Need multi-vector storage per record (dense + sparse)-- Building real-time recommendation systems--**Key features:**-- **Rust-powered**: Memory-safe, high performance-- **Rich filtering**: Filter by any payload field during search-- **Multiple vectors**: Dense, sparse, multi-dense per point-- **Quantization**: Scalar, product, binary for memory efficiency-- **Distributed**: Raft consensus, sharding, replication-- **REST + gRPC**: Both APIs with full feature parity--**Use alternatives instead:**-- **Chroma**: Simpler setup, embedded use cases-- **FAISS**: Maximum raw speed, research/batch processing-- **Pinecone**: Fully managed, zero ops preferred-- **Weaviate**: GraphQL preference, built-in vectorizers--## Quick start--### Installation--```bash-# Python client-pip install qdrant-client--# Docker (recommended for development)-docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant--# Docker with persistent storage-docker run -p 6333:6333 -p 6334:6334 \- -v $(pwd)/qdrant_storage:/qdrant/storage \- qdrant/qdrant-```--### Basic usage--```python-from qdrant_client import QdrantClient-from qdrant_client.models import Distance, VectorParams, PointStruct--# Connect to Qdrant-client = QdrantClient(host="localhost", port=6333)--# Create collection-client.create_collection(- collection_name="documents",- vectors_config=VectorParams(size=384, distance=Distance.COSINE)-)--# Insert vectors with payload-client.upsert(- collection_name="documents",- points=[- PointStruct(- id=1,- vector=[0.1, 0.2, ...], # 384-dim vector- payload={"title": "Doc 1", "category": "tech"}- ),- PointStruct(- id=2,- vector=[0.3, 0.4, ...],- payload={"title": "Doc 2", "category": "science"}- )- ]-)--# Search with filtering (query_points is the current API; client.search is removed in qdrant-client 1.14+)-response = client.query_points(- collection_name="documents",- query=[0.15, 0.25, ...],- query_filter={- "must": [{"key": "category", "match": {"value": "tech"}}]- },- limit=10-)--for point in response.points:- print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")-```--## Core concepts--### Points - Basic data unit--```python-from qdrant_client.models import PointStruct--# Point = ID + Vector(s) + Payload-point = PointStruct(- id=123, # Integer or UUID string- vector=[0.1, 0.2, 0.3, ...], # Dense vector- payload={ # Arbitrary JSON metadata- "title": "Document title",- "category": "tech",- "timestamp": 1699900000,- "tags": ["python", "ml"]- }-)--# Batch upsert (recommended)-client.upsert(- collection_name="documents",- points=[point1, point2, point3],- wait=True # Wait for indexing-)-```--### Collections - Vector containers--```python-from qdrant_client.models import VectorParams, Distance, HnswConfigDiff--# Create with HNSW configuration-client.create_collection(- collection_name="documents",- vectors_config=VectorParams(- size=384, # Vector dimensions- distance=Distance.COSINE # COSINE, EUCLID, DOT, MANHATTAN- ),- hnsw_config=HnswConfigDiff(- m=16, # Connections per node (default 16)- ef_construct=100, # Build-time accuracy (default 100)- full_scan_threshold=10000 # Switch to brute force below this- ),- on_disk_payload=True # Store payload on disk-)--# Collection info-info = client.get_collection("documents")-print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")-```--### Distance metrics--| Metric | Use Case | Range |-|--------|----------|-------|-| `COSINE` | Text embeddings, normalized vectors | 0 to 2 |-| `EUCLID` | Spatial data, image features | 0 to ∞ |-| `DOT` | Recommendations, unnormalized | -∞ to ∞ |-| `MANHATTAN` | Sparse features, discrete data | 0 to ∞ |--## Search operations--### Basic search--```python-# Simple nearest neighbor search (returns a QueryResponse; use .points)-response = client.query_points(- collection_name="documents",- query=[0.1, 0.2, ...],- limit=10,- with_payload=True,- with_vectors=False # Don't return vectors (faster)-)-results = response.points-```--### Filtered search--```python-from qdrant_client.models import Filter, FieldCondition, MatchValue, Range--# Complex filtering-response = client.query_points(- collection_name="documents",- query=query_embedding,- query_filter=Filter(- must=[- FieldCondition(key="category", match=MatchValue(value="tech")),- FieldCondition(key="timestamp", range=Range(gte=1699000000))- ],- must_not=[- FieldCondition(key="status", match=MatchValue(value="archived"))- ]- ),- limit=10-).points--# Shorthand filter syntax-response = client.query_points(- collection_name="documents",- query=query_embedding,- query_filter={- "must": [- {"key": "category", "match": {"value": "tech"}},- {"key": "price", "range": {"gte": 10, "lte": 100}}- ]- },- limit=10-).points-```--### Batch search--```python-from qdrant_client.models import QueryRequest--# Multiple queries in one request (search_batch is replaced by query_batch_points)-responses = client.query_batch_points(- collection_name="documents",- requests=[- QueryRequest(query=[0.1, ...], limit=5),- QueryRequest(query=[0.2, ...], limit=5, filter={"must": [...]}),- QueryRequest(query=[0.3, ...], limit=10)- ]-)-# Each element is a QueryResponse; use .points-for resp in responses:- for point in resp.points:- print(point.id, point.score)-```--## RAG integration--### With sentence-transformers--```python-from sentence_transformers import SentenceTransformer-from qdrant_client import QdrantClient-from qdrant_client.models import VectorParams, Distance, PointStruct--# Initialize-encoder = SentenceTransformer("all-MiniLM-L6-v2")-client = QdrantClient(host="localhost", port=6333)--# Create collection-client.create_collection(- collection_name="knowledge_base",- vectors_config=VectorParams(size=384, distance=Distance.COSINE)-)--# Index documents-documents = [- {"id": 1, "text": "Python is a programming language", "source": "wiki"},- {"id": 2, "text": "Machine learning uses algorithms", "source": "textbook"},-]--points = [- PointStruct(- id=doc["id"],- vector=encoder.encode(doc["text"]).tolist(),- payload={"text": doc["text"], "source": doc["source"]}- )- for doc in documents-]-client.upsert(collection_name="knowledge_base", points=points)--# RAG retrieval-def retrieve(query: str, top_k: int = 5) -> list[dict]:- query_vector = encoder.encode(query).tolist()- response = client.query_points(- collection_name="knowledge_base",- query=query_vector,- limit=top_k- )- return [{"text": r.payload["text"], "score": r.score} for r in response.points]--# Use in RAG pipeline-context = retrieve("What is Python?")-prompt = f"Context: {context}\n\nQuestion: What is Python?"-```--### With LangChain--```python-from langchain_community.vectorstores import Qdrant-from langchain_community.embeddings import HuggingFaceEmbeddings--embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")-vectorstore = Qdrant.from_documents(documents, embeddings, url="http://localhost:6333", collection_name="docs")-retriever = vectorstore.as_retriever(search_kwargs={"k": 5})-```--### With LlamaIndex--```python-from llama_index.vector_stores.qdrant import QdrantVectorStore-from llama_index.core import VectorStoreIndex, StorageContext--vector_store = QdrantVectorStore(client=client, collection_name="llama_docs")-storage_context = StorageContext.from_defaults(vector_store=vector_store)-index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)-query_engine = index.as_query_engine()-```--## Multi-vector support--### Named vectors (different embedding models)--```python-from qdrant_client.models import VectorParams, Distance--# Collection with multiple vector types-client.create_collection(- collection_name="hybrid_search",- vectors_config={- "dense": VectorParams(size=384, distance=Distance.COSINE),- "sparse": VectorParams(size=30000, distance=Distance.DOT)- }-)--# Insert with named vectors-client.upsert(- collection_name="hybrid_search",- points=[- PointStruct(- id=1,- vector={- "dense": dense_embedding,- "sparse": sparse_embedding- },- payload={"text": "document text"}- )- ]-)--# Search specific named vector (pass the vector name via `using`)-response = client.query_points(- collection_name="hybrid_search",- query=query_dense,- using="dense", # Specify which named vector to search- limit=10-)-results = response.points-```--### Sparse vectors (BM25, SPLADE)--```python-from qdrant_client.models import SparseVectorParams, SparseIndexParams, SparseVector--# Collection with sparse vectors-client.create_collection(- collection_name="sparse_search",- vectors_config={},- sparse_vectors_config={"text": SparseVectorParams(index=SparseIndexParams(on_disk=False))}-)--# Insert sparse vector-client.upsert(- collection_name="sparse_search",- points=[PointStruct(id=1, vector={"text": SparseVector(indices=[1, 5, 100], values=[0.5, 0.8, 0.2])}, payload={"text": "document"})]-)-```--## Quantization (memory optimization)--```python-from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType--# Scalar quantization (4x memory reduction)-client.create_collection(- collection_name="quantized",- vectors_config=VectorParams(size=384, distance=Distance.COSINE),- quantization_config=ScalarQuantization(- scalar=ScalarQuantizationConfig(- type=ScalarType.INT8,- quantile=0.99, # Clip outliers- always_ram=True # Keep quantized in RAM- )- )-)--# Search with rescoring-response = client.query_points(- collection_name="quantized",- query=query,- search_params={"quantization": {"rescore": True}}, # Rescore top results- limit=10-)-results = response.points-```--## Payload indexing--```python-from qdrant_client.models import PayloadSchemaType--# Create payload index for faster filtering-client.create_payload_index(- collection_name="documents",- field_name="category",- field_schema=PayloadSchemaType.KEYWORD-)--client.create_payload_index(- collection_name="documents",- field_name="timestamp",- field_schema=PayloadSchemaType.INTEGER-)--# Index types: KEYWORD, INTEGER, FLOAT, GEO, TEXT (full-text), BOOL-```--## Production deployment--### Qdrant Cloud--```python-from qdrant_client import QdrantClient--# Connect to Qdrant Cloud-client = QdrantClient(- url="https://your-cluster.cloud.qdrant.io",- api_key="your-api-key"-)-```--### Performance tuning--```python-# Optimize for search speed (higher recall)-client.update_collection(- collection_name="documents",- hnsw_config=HnswConfigDiff(ef_construct=200, m=32)-)--# Optimize for indexing speed (bulk loads)-client.update_collection(- collection_name="documents",- optimizer_config={"indexing_threshold": 20000}-)-```--## Best practices--1. **Batch operations** - Use batch upsert/search for efficiency-2. **Payload indexing** - Index fields used in filters-3. **Quantization** - Enable for large collections (>1M vectors)-4. **Sharding** - Use for collections >10M vectors-5. **On-disk storage** - Enable `on_disk_payload` for large payloads-6. **Connection pooling** - Reuse client instances--## Common issues--**Slow search with filters:**-```python-# Create payload index for filtered fields-client.create_payload_index(- collection_name="docs",- field_name="category",- field_schema=PayloadSchemaType.KEYWORD-)-```--**Out of memory:**-```python-# Enable quantization and on-disk storage-client.create_collection(- collection_name="large_collection",- vectors_config=VectorParams(size=384, distance=Distance.COSINE),- quantization_config=ScalarQuantization(...),- on_disk_payload=True-)-```--**Connection issues:**-```python-# Use timeout and retry-client = QdrantClient(- host="localhost",- port=6333,- timeout=30,- prefer_grpc=True # gRPC for better performance-)-```--## References--- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/qdrant/references/advanced-usage.md)** - Distributed mode, hybrid search, recommendations-- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/qdrant/references/troubleshooting.md)** - Common issues, debugging, performance tuning--## Resources--- **GitHub**: https://github.com/qdrant/qdrant (22k+ stars)-- **Docs**: https://qdrant.tech/documentation/-- **Python Client**: https://github.com/qdrant/qdrant-client-- **Cloud**: https://cloud.qdrant.io-- **Version**: 1.14.0+-- **License**: Apache 2.0diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md b/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.mddeleted file mode 100644index 8bc55a8d88c..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md+++ /dev/null@@ -1,542 +0,0 @@-----title: "Stable Diffusion — Text-to-image generation, inpainting, and img2img"-sidebar_label: "Stable Diffusion"-description: "Text-to-image generation, inpainting, and img2img"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Stable Diffusion--Text-to-image generation, inpainting, and img2img.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/stable-diffusion` |-| Path | `optional-skills/mlops/stable-diffusion` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `diffusers>=0.30.0`, `transformers>=4.41.0`, `accelerate>=0.31.0`, `torch>=2.0.0` |-| Platforms | linux, macos, windows |-| Tags | `Image Generation`, `Stable Diffusion`, `Diffusers`, `Text-to-Image`, `Multimodal`, `Computer Vision` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Stable Diffusion Image Generation--Guide to generating images with Stable Diffusion using the HuggingFace Diffusers library.--## When to use Stable Diffusion--**Use Stable Diffusion when:**-- Generating images from text descriptions-- Performing image-to-image translation (style transfer, enhancement)-- Inpainting (filling in masked regions)-- Outpainting (extending images beyond boundaries)-- Creating variations of existing images-- Building custom image generation workflows--**Key features:**-- **Text-to-Image**: Generate images from natural language prompts-- **Image-to-Image**: Transform existing images with text guidance-- **Inpainting**: Fill masked regions with context-aware content-- **ControlNet**: Add spatial conditioning (edges, poses, depth)-- **LoRA Support**: Efficient fine-tuning and style adaptation-- **Multiple Models**: SD 1.5, SDXL, SD 3.0, Flux support--**Use alternatives instead:**-- **DALL-E 3**: For API-based generation without GPU-- **Midjourney**: For artistic, stylized outputs-- **Imagen**: For Google Cloud integration-- **Leonardo.ai**: For web-based creative workflows--## Quick start--### Installation--```bash-pip install diffusers transformers accelerate torch-pip install xformers # Optional: memory-efficient attention-```--### Basic text-to-image--```python-from diffusers import DiffusionPipeline-import torch--# Load pipeline (auto-detects model type)-pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-)-pipe.to("cuda")--# Generate image-image = pipe(- "A serene mountain landscape at sunset, highly detailed",- num_inference_steps=50,- guidance_scale=7.5-).images[0]--image.save("output.png")-```--### Using SDXL (higher quality)--```python-from diffusers import AutoPipelineForText2Image-import torch--pipe = AutoPipelineForText2Image.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16,- variant="fp16"-)-pipe.to("cuda")--# Enable memory optimization-pipe.enable_model_cpu_offload()--image = pipe(- prompt="A futuristic city with flying cars, cinematic lighting",- height=1024,- width=1024,- num_inference_steps=30-).images[0]-```--## Architecture overview--### Three-pillar design--Diffusers is built around three core components:--<!-- ascii-guard-ignore -->-```-Pipeline (orchestration)-├── Model (neural networks)-│ ├── UNet / Transformer (noise prediction)-│ ├── VAE (latent encoding/decoding)-│ └── Text Encoder (CLIP/T5)-└── Scheduler (denoising algorithm)-```-<!-- ascii-guard-ignore-end -->--### Pipeline inference flow--```-Text Prompt → Text Encoder → Text Embeddings- ↓-Random Noise → [Denoising Loop] ← Scheduler- ↓- Predicted Noise- ↓- VAE Decoder → Final Image-```--## Core concepts--### Pipelines--Pipelines orchestrate complete workflows:--| Pipeline | Purpose |-|----------|---------|-| `StableDiffusionPipeline` | Text-to-image (SD 1.x/2.x) |-| `StableDiffusionXLPipeline` | Text-to-image (SDXL) |-| `StableDiffusion3Pipeline` | Text-to-image (SD 3.0) |-| `FluxPipeline` | Text-to-image (Flux models) |-| `StableDiffusionImg2ImgPipeline` | Image-to-image |-| `StableDiffusionInpaintPipeline` | Inpainting |--### Schedulers--Schedulers control the denoising process:--| Scheduler | Steps | Quality | Use Case |-|-----------|-------|---------|----------|-| `EulerDiscreteScheduler` | 20-50 | Good | Default choice |-| `EulerAncestralDiscreteScheduler` | 20-50 | Good | More variation |-| `DPMSolverMultistepScheduler` | 15-25 | Excellent | Fast, high quality |-| `DDIMScheduler` | 50-100 | Good | Deterministic |-| `LCMScheduler` | 4-8 | Good | Very fast |-| `UniPCMultistepScheduler` | 15-25 | Excellent | Fast convergence |--### Swapping schedulers--```python-from diffusers import DPMSolverMultistepScheduler--# Swap for faster generation-pipe.scheduler = DPMSolverMultistepScheduler.from_config(- pipe.scheduler.config-)--# Now generate with fewer steps-image = pipe(prompt, num_inference_steps=20).images[0]-```--## Generation parameters--### Key parameters--| Parameter | Default | Description |-|-----------|---------|-------------|-| `prompt` | Required | Text description of desired image |-| `negative_prompt` | None | What to avoid in the image |-| `num_inference_steps` | 50 | Denoising steps (more = better quality) |-| `guidance_scale` | 7.5 | Prompt adherence (7-12 typical) |-| `height`, `width` | 512/1024 | Output dimensions (multiples of 8) |-| `generator` | None | Torch generator for reproducibility |-| `num_images_per_prompt` | 1 | Batch size |--### Reproducible generation--```python-import torch--generator = torch.Generator(device="cuda").manual_seed(42)--image = pipe(- prompt="A cat wearing a top hat",- generator=generator,- num_inference_steps=50-).images[0]-```--### Negative prompts--```python-image = pipe(- prompt="Professional photo of a dog in a garden",- negative_prompt="blurry, low quality, distorted, ugly, bad anatomy",- guidance_scale=7.5-).images[0]-```--## Image-to-image--Transform existing images with text guidance:--```python-from diffusers import AutoPipelineForImage2Image-from PIL import Image--pipe = AutoPipelineForImage2Image.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-).to("cuda")--init_image = Image.open("input.jpg").resize((512, 512))--image = pipe(- prompt="A watercolor painting of the scene",- image=init_image,- strength=0.75, # How much to transform (0-1)- num_inference_steps=50-).images[0]-```--## Inpainting--Fill masked regions:--```python-from diffusers import AutoPipelineForInpainting-from PIL import Image--pipe = AutoPipelineForInpainting.from_pretrained(- "runwayml/stable-diffusion-inpainting",- torch_dtype=torch.float16-).to("cuda")--image = Image.open("photo.jpg")-mask = Image.open("mask.png") # White = inpaint region--result = pipe(- prompt="A red car parked on the street",- image=image,- mask_image=mask,- num_inference_steps=50-).images[0]-```--## ControlNet--Add spatial conditioning for precise control:--```python-from diffusers import StableDiffusionControlNetPipeline, ControlNetModel-import torch--# Load ControlNet for edge conditioning-controlnet = ControlNetModel.from_pretrained(- "lllyasviel/control_v11p_sd15_canny",- torch_dtype=torch.float16-)--pipe = StableDiffusionControlNetPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- controlnet=controlnet,- torch_dtype=torch.float16-).to("cuda")--# Use Canny edge image as control-control_image = get_canny_image(input_image)--image = pipe(- prompt="A beautiful house in the style of Van Gogh",- image=control_image,- num_inference_steps=30-).images[0]-```--### Available ControlNets--| ControlNet | Input Type | Use Case |-|------------|------------|----------|-| `canny` | Edge maps | Preserve structure |-| `openpose` | Pose skeletons | Human poses |-| `depth` | Depth maps | 3D-aware generation |-| `normal` | Normal maps | Surface details |-| `mlsd` | Line segments | Architectural lines |-| `scribble` | Rough sketches | Sketch-to-image |--## LoRA adapters--Load fine-tuned style adapters:--```python-from diffusers import DiffusionPipeline--pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-).to("cuda")--# Load LoRA weights-pipe.load_lora_weights("path/to/lora", weight_name="style.safetensors")--# Generate with LoRA style-image = pipe("A portrait in the trained style").images[0]--# Adjust LoRA strength-pipe.fuse_lora(lora_scale=0.8)--# Unload LoRA-pipe.unload_lora_weights()-```--### Multiple LoRAs--```python-# Load multiple LoRAs-pipe.load_lora_weights("lora1", adapter_name="style")-pipe.load_lora_weights("lora2", adapter_name="character")--# Set weights for each-pipe.set_adapters(["style", "character"], adapter_weights=[0.7, 0.5])--image = pipe("A portrait").images[0]-```--## Memory optimization--### Enable CPU offloading--```python-# Model CPU offload - moves models to CPU when not in use-pipe.enable_model_cpu_offload()--# Sequential CPU offload - more aggressive, slower-pipe.enable_sequential_cpu_offload()-```--### Attention slicing--```python-# Reduce memory by computing attention in chunks-pipe.enable_attention_slicing()--# Or specific chunk size-pipe.enable_attention_slicing("max")-```--### xFormers memory-efficient attention--```python-# Requires xformers package-pipe.enable_xformers_memory_efficient_attention()-```--### VAE slicing for large images--```python-# Decode latents in tiles for large images-pipe.enable_vae_slicing()-pipe.enable_vae_tiling()-```--## Model variants--### Loading different precisions--```python-# FP16 (recommended for GPU)-pipe = DiffusionPipeline.from_pretrained(- "model-id",- torch_dtype=torch.float16,- variant="fp16"-)--# BF16 (better precision, requires Ampere+ GPU)-pipe = DiffusionPipeline.from_pretrained(- "model-id",- torch_dtype=torch.bfloat16-)-```--### Loading specific components--```python-from diffusers import UNet2DConditionModel, AutoencoderKL--# Load custom VAE-vae = AutoencoderKL.from_pretrained("stabilityai/sd-vae-ft-mse")--# Use with pipeline-pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- vae=vae,- torch_dtype=torch.float16-)-```--## Batch generation--Generate multiple images efficiently:--```python-# Multiple prompts-prompts = [- "A cat playing piano",- "A dog reading a book",- "A bird painting a picture"-]--images = pipe(prompts, num_inference_steps=30).images--# Multiple images per prompt-images = pipe(- "A beautiful sunset",- num_images_per_prompt=4,- num_inference_steps=30-).images-```--## Common workflows--### Workflow 1: High-quality generation--```python-from diffusers import StableDiffusionXLPipeline, DPMSolverMultistepScheduler-import torch--# 1. Load SDXL with optimizations-pipe = StableDiffusionXLPipeline.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16,- variant="fp16"-)-pipe.to("cuda")-pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)-pipe.enable_model_cpu_offload()--# 2. Generate with quality settings-image = pipe(- prompt="A majestic lion in the savanna, golden hour lighting, 8k, detailed fur",- negative_prompt="blurry, low quality, cartoon, anime, sketch",- num_inference_steps=30,- guidance_scale=7.5,- height=1024,- width=1024-).images[0]-```--### Workflow 2: Fast prototyping--```python-from diffusers import AutoPipelineForText2Image, LCMScheduler-import torch--# Use LCM for 4-8 step generation-pipe = AutoPipelineForText2Image.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16-).to("cuda")--# Load LCM LoRA for fast generation-pipe.load_lora_weights("latent-consistency/lcm-lora-sdxl")-pipe.scheduler = LCMScheduler.from_config(pipe.scheduler.config)-pipe.fuse_lora()--# Generate in ~1 second-image = pipe(- "A beautiful landscape",- num_inference_steps=4,- guidance_scale=1.0-).images[0]-```--## Common issues--**CUDA out of memory:**-```python-# Enable memory optimizations-pipe.enable_model_cpu_offload()-pipe.enable_attention_slicing()-pipe.enable_vae_slicing()--# Or use lower precision-pipe = DiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16)-```--**Black/noise images:**-```python-# Check VAE configuration-# Use safety checker bypass if needed-pipe.safety_checker = None--# Ensure proper dtype consistency-pipe = pipe.to(dtype=torch.float16)-```--**Slow generation:**-```python-# Use faster scheduler-from diffusers import DPMSolverMultistepScheduler-pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)--# Reduce steps-image = pipe(prompt, num_inference_steps=20).images[0]-```--## References--- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/stable-diffusion/references/advanced-usage.md)** - Custom pipelines, fine-tuning, deployment-- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/stable-diffusion/references/troubleshooting.md)** - Common issues and solutions--## Resources--- **Documentation**: https://huggingface.co/docs/diffusers-- **Repository**: https://github.com/huggingface/diffusers-- **Model Hub**: https://huggingface.co/models?library=diffusers-- **Discord**: https://discord.gg/diffusersdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md b/website/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.mddeleted file mode 100644index d46746137ad..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md+++ /dev/null@@ -1,512 +0,0 @@-----title: "Trl Fine Tuning — TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF"-sidebar_label: "Trl Fine Tuning"-description: "TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Trl Fine Tuning--TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/trl-fine-tuning` |-| Path | `optional-skills/mlops/training/trl-fine-tuning` |-| Version | `1.0.1` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `trl`, `transformers`, `datasets`, `peft`, `accelerate`, `torch` |-| Platforms | linux, macos, windows |-| Tags | `Post-Training`, `TRL`, `Reinforcement Learning`, `Fine-Tuning`, `SFT`, `DPO`, `GRPO`, `RLOO`, `RLHF`, `Preference Alignment`, `HuggingFace` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# TRL - Transformer Reinforcement Learning--## Quick start--TRL provides post-training methods for aligning language models with human preferences.--**Installation**:-```bash-pip install trl transformers datasets peft accelerate-```--**Supervised Fine-Tuning** (instruction tuning):-```python-from trl import SFTTrainer--trainer = SFTTrainer(- model="Qwen/Qwen2.5-0.5B",- train_dataset=dataset, # Prompt-completion pairs-)-trainer.train()-```--**DPO** (align with preferences):-```python-from trl import DPOTrainer, DPOConfig--config = DPOConfig(output_dir="model-dpo", beta=0.1)-trainer = DPOTrainer(- model=model,- args=config,- train_dataset=preference_dataset, # chosen/rejected pairs- processing_class=tokenizer-)-trainer.train()-```--## Common workflows--### Workflow 1: Full RLHF pipeline (SFT → Reward Model → RLOO)--Complete pipeline from base model to human-aligned model.--> **Note (TRL 1.x):** PPO has been **removed** from TRL — `PPOTrainer`, `PPOConfig`, and-> `python -m trl.scripts.ppo` no longer exist. Use an online-RL trainer TRL still ships:-> **RLOO** (`RLOOTrainer` / `trl rloo`) is the closest drop-in for a reward-model-driven-> RLHF pipeline, and **GRPO** (`GRPOTrainer` / `trl grpo`, see Workflow 3) is the-> memory-efficient alternative. The step below uses RLOO.--Copy this checklist:--```-RLHF Training:-- [ ] Step 1: Supervised fine-tuning (SFT)-- [ ] Step 2: Train reward model-- [ ] Step 3: RLOO reinforcement learning-- [ ] Step 4: Evaluate aligned model-```--**Step 1: Supervised fine-tuning**--Train base model on instruction-following data:--```python-from transformers import AutoModelForCausalLM, AutoTokenizer-from trl import SFTTrainer, SFTConfig-from datasets import load_dataset--# Load model-model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B")-tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B")--# Load instruction dataset-dataset = load_dataset("trl-lib/Capybara", split="train")--# Configure training-training_args = SFTConfig(- output_dir="Qwen2.5-0.5B-SFT",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=2e-5,- logging_steps=10,- save_strategy="epoch"-)--# Train-trainer = SFTTrainer(- model=model,- args=training_args,- train_dataset=dataset,- processing_class=tokenizer-)-trainer.train()-trainer.save_model()-```--**Step 2: Train reward model**--Train model to predict human preferences:--```python-from transformers import AutoModelForSequenceClassification-from trl import RewardTrainer, RewardConfig--# Load SFT model as base-model = AutoModelForSequenceClassification.from_pretrained(- "Qwen2.5-0.5B-SFT",- num_labels=1 # Single reward score-)-tokenizer = AutoTokenizer.from_pretrained("Qwen2.5-0.5B-SFT")--# Load preference data (chosen/rejected pairs)-dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")--# Configure training-training_args = RewardConfig(- output_dir="Qwen2.5-0.5B-Reward",- per_device_train_batch_size=2,- num_train_epochs=1,- learning_rate=1e-5-)--# Train reward model-trainer = RewardTrainer(- model=model,- args=training_args,- processing_class=tokenizer,- train_dataset=dataset-)-trainer.train()-trainer.save_model()-```--**Step 3: RLOO reinforcement learning**--Optimize policy using the reward model. PPO was removed in TRL 1.x; use the RLOO CLI-(`trl rloo`) with the trained reward model passed via `--reward_model_name_or_path`:--```bash-trl rloo \- --model_name_or_path Qwen2.5-0.5B-SFT \- --reward_model_name_or_path Qwen2.5-0.5B-Reward \- --dataset_name trl-internal-testing/descriptiveness-sentiment-trl-style \- --output_dir Qwen2.5-0.5B-RLOO \- --learning_rate 3e-6 \- --per_device_train_batch_size 64 \- --num_generations 4-```--Equivalent Python (`RLOOTrainer` / `RLOOConfig`):-```python-from trl import RLOOTrainer, RLOOConfig-from transformers import AutoModelForSequenceClassification, AutoTokenizer--reward_model = AutoModelForSequenceClassification.from_pretrained(- "Qwen2.5-0.5B-Reward", num_labels=1-)--config = RLOOConfig(- output_dir="Qwen2.5-0.5B-RLOO",- per_device_train_batch_size=64,- learning_rate=3e-6,- num_generations=4,-)--trainer = RLOOTrainer(- model="Qwen2.5-0.5B-SFT",- reward_funcs=reward_model, # a reward model (or a callable reward function)- args=config,- train_dataset=dataset, # prompt-only dataset- processing_class=tokenizer,-)-trainer.train()-```--**Step 4: Evaluate**--```python-from transformers import pipeline--# Load aligned model-generator = pipeline("text-generation", model="Qwen2.5-0.5B-RLOO")--# Test-prompt = "Explain quantum computing to a 10-year-old"-output = generator(prompt, max_length=200)[0]["generated_text"]-print(output)-```--### Workflow 2: Simple preference alignment with DPO--Align model with preferences without reward model.--Copy this checklist:--```-DPO Training:-- [ ] Step 1: Prepare preference dataset-- [ ] Step 2: Configure DPO-- [ ] Step 3: Train with DPOTrainer-- [ ] Step 4: Evaluate alignment-```--**Step 1: Prepare preference dataset**--Dataset format:-```json-{- "prompt": "What is the capital of France?",- "chosen": "The capital of France is Paris.",- "rejected": "I don't know."-}-```--Load dataset:-```python-from datasets import load_dataset--dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")-# Or load your own-# dataset = load_dataset("json", data_files="preferences.json")-```--**Step 2: Configure DPO**--```python-from trl import DPOConfig--config = DPOConfig(- output_dir="Qwen2.5-0.5B-DPO",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=5e-7,- beta=0.1, # KL penalty strength- max_prompt_length=512,- max_length=1024,- logging_steps=10-)-```--**Step 3: Train with DPOTrainer**--```python-from transformers import AutoModelForCausalLM, AutoTokenizer-from trl import DPOTrainer--model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")-tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")--trainer = DPOTrainer(- model=model,- args=config,- train_dataset=dataset,- processing_class=tokenizer-)--trainer.train()-trainer.save_model()-```--**CLI alternative**:-```bash-trl dpo \- --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \- --dataset_name argilla/Capybara-Preferences \- --output_dir Qwen2.5-0.5B-DPO \- --per_device_train_batch_size 4 \- --learning_rate 5e-7 \- --beta 0.1-```--### Workflow 3: Memory-efficient online RL with GRPO--Train with reinforcement learning using minimal memory.--For in-depth GRPO guidance — reward function design, critical training insights (loss behavior, mode collapse, tuning), and advanced multi-stage patterns — see **[references/grpo-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/grpo-training.md)**. A production-ready training script is in **[templates/basic_grpo_training.py](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/templates/basic_grpo_training.py)**.--Copy this checklist:--```-GRPO Training:-- [ ] Step 1: Define reward function-- [ ] Step 2: Configure GRPO-- [ ] Step 3: Train with GRPOTrainer-```--**Step 1: Define reward function**--```python-def reward_function(completions, **kwargs):- """- Compute rewards for completions.-- Args:- completions: List of generated texts-- Returns:- List of reward scores (floats)- """- rewards = []- for completion in completions:- # Example: reward based on length and unique words- score = len(completion.split()) # Favor longer responses- score += len(set(completion.lower().split())) # Reward unique words- rewards.append(score)- return rewards-```--Or use a reward model:-```python-from transformers import pipeline--reward_model = pipeline("text-classification", model="reward-model-path")--def reward_from_model(completions, prompts, **kwargs):- # Combine prompt + completion- full_texts = [p + c for p, c in zip(prompts, completions)]- # Get reward scores- results = reward_model(full_texts)- return [r["score"] for r in results]-```--**Step 2: Configure GRPO**--```python-from trl import GRPOConfig--config = GRPOConfig(- output_dir="Qwen2-GRPO",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=1e-5,- num_generations=4, # Generate 4 completions per prompt- max_new_tokens=128-)-```--**Step 3: Train with GRPOTrainer**--```python-from datasets import load_dataset-from trl import GRPOTrainer--# Load prompt-only dataset-dataset = load_dataset("trl-lib/tldr", split="train")--trainer = GRPOTrainer(- model="Qwen/Qwen2-0.5B-Instruct",- reward_funcs=reward_function, # Your reward function- args=config,- train_dataset=dataset-)--trainer.train()-```--**CLI**:-```bash-trl grpo \- --model_name_or_path Qwen/Qwen2-0.5B-Instruct \- --dataset_name trl-lib/tldr \- --output_dir Qwen2-GRPO \- --num_generations 4-```--## When to use vs alternatives--**Use TRL when:**-- Need to align model with human preferences-- Have preference data (chosen/rejected pairs)-- Want to use reinforcement learning (RLOO, GRPO)-- Need reward model training-- Doing RLHF (full pipeline)--**Method selection**:-- **SFT**: Have prompt-completion pairs, want basic instruction following-- **DPO**: Have preferences, want simple alignment (no reward model needed)-- **RLOO**: Have a reward model, want online RL (the reward-model-driven RLHF path; PPO was removed in TRL 1.x)-- **GRPO**: Memory-constrained, want online RL with reward functions-- **Reward Model**: Building RLHF pipeline, need to score generations--**Use alternatives instead:**-- **HuggingFace Trainer**: Basic fine-tuning without RL-- **Axolotl**: YAML-based training configuration-- **LitGPT**: Educational, minimal fine-tuning-- **Unsloth**: Fast LoRA training--## Common issues--**Issue: OOM during DPO training**--Reduce batch size and sequence length:-```python-config = DPOConfig(- per_device_train_batch_size=1, # Reduce from 4- max_length=512, # Reduce from 1024- gradient_accumulation_steps=8 # Maintain effective batch-)-```--Or use gradient checkpointing:-```python-model.gradient_checkpointing_enable()-```--**Issue: Poor alignment quality**--Tune beta parameter:-```python-# Higher beta = more conservative (stays closer to reference)-config = DPOConfig(beta=0.5) # Default 0.1--# Lower beta = more aggressive alignment-config = DPOConfig(beta=0.01)-```--**Issue: Reward model not learning**--Check loss type and learning rate:-```python-config = RewardConfig(- learning_rate=1e-5, # Try different LR- num_train_epochs=3 # Train longer-)-```--Ensure preference dataset has clear winners:-```python-# Verify dataset-print(dataset[0])-# Should have clear chosen > rejected-```--**Issue: Online RL (RLOO/GRPO) training unstable**--Adjust the KL/beta regularization toward the reference policy:-```python-from trl import RLOOConfig--config = RLOOConfig(- beta=0.05, # KL coefficient toward the reference model (increase for stability)- num_generations=4, # more samples per prompt = lower-variance advantage estimates-)-```--## Advanced topics--**SFT training guide**: See [references/sft-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/sft-training.md) for dataset formats, chat templates, packing strategies, and multi-GPU training.--**DPO variants**: See [references/dpo-variants.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/dpo-variants.md) for IPO, cDPO, RPO, and other DPO loss functions with recommended hyperparameters.--**Reward modeling**: See [references/reward-modeling.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/reward-modeling.md) for outcome vs process rewards, Bradley-Terry loss, and reward model evaluation.--**Online RL methods**: See [references/online-rl.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/online-rl.md) for PPO, GRPO, RLOO, and OnlineDPO with detailed configurations.--**GRPO deep dive**: See [references/grpo-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/grpo-training.md) for expert-level GRPO patterns — reward function design philosophy, training insights (why loss increases, mode collapse detection), hyperparameter tuning, multi-stage training, and troubleshooting. Production-ready template in [templates/basic_grpo_training.py](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/templates/basic_grpo_training.py).--## Hardware requirements--- **GPU**: NVIDIA (CUDA required)-- **VRAM**: Depends on model and method- - SFT 7B: 16GB (with LoRA)- - DPO 7B: 24GB (stores reference model)- - RLOO 7B: 40GB (policy + reward model)- - GRPO 7B: 24GB (more memory efficient)-- **Multi-GPU**: Supported via `accelerate`-- **Mixed precision**: BF16 recommended (A100/H100)--**Memory optimization**:-- Use LoRA/QLoRA for all methods-- Enable gradient checkpointing-- Use smaller batch sizes with gradient accumulation--## Resources--- Docs: https://huggingface.co/docs/trl/-- GitHub: https://github.com/huggingface/trl-- Papers:- - "Training language models to follow instructions with human feedback" (InstructGPT, 2022)- - "Direct Preference Optimization: Your Language Model is Secretly a Reward Model" (DPO, 2023)- - "Group Relative Policy Optimization" (GRPO, 2024)-- Examples: https://github.com/huggingface/trl/tree/main/examples/scriptsdiff --git a/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md b/website/docs/user-guide/skills/optional/mlops/mlops-whisper.mddeleted file mode 100644index 458316b67c1..00000000000--- a/website/docs/user-guide/skills/optional/mlops/mlops-whisper.md+++ /dev/null@@ -1,336 +0,0 @@-----title: "Whisper — Transcribe and translate speech in 99 languages"-sidebar_label: "Whisper"-description: "Transcribe and translate speech in 99 languages"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Whisper--Transcribe and translate speech in 99 languages.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/mlops/whisper` |-| Path | `optional-skills/mlops/whisper` |-| Version | `1.0.0` |-| Author | Orchestra Research |-| License | MIT |-| Dependencies | `openai-whisper`, `transformers`, `torch` |-| Platforms | linux, macos |-| Tags | `Whisper`, `Speech Recognition`, `ASR`, `Multimodal`, `Multilingual`, `OpenAI`, `Speech-To-Text`, `Transcription`, `Translation`, `Audio Processing` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Whisper - Robust Speech Recognition--OpenAI's multilingual speech recognition model.--## When to use Whisper--**Use when:**-- Speech-to-text transcription (99 languages)-- Podcast/video transcription-- Meeting notes automation-- Translation to English-- Noisy audio transcription-- Multilingual audio processing--**Metrics**:-- **72,900+ GitHub stars**-- 99 languages supported-- Trained on 680,000 hours of audio-- MIT License--**Use alternatives instead**:-- **AssemblyAI**: Managed API, speaker diarization-- **Deepgram**: Real-time streaming ASR-- **Google Speech-to-Text**: Cloud-based--## Quick start--### Installation--```bash-# Requires Python 3.8-3.11-pip install -U openai-whisper--# Requires ffmpeg-# macOS: brew install ffmpeg-# Ubuntu: sudo apt install ffmpeg-# Windows: choco install ffmpeg-```--### Basic transcription--```python-import whisper--# Load model-model = whisper.load_model("base")--# Transcribe-result = model.transcribe("audio.mp3")--# Print text-print(result["text"])--# Access segments-for segment in result["segments"]:- print(f"[{segment['start']:.2f}s - {segment['end']:.2f}s] {segment['text']}")-```--## Model sizes--```python-# Available models-models = ["tiny", "base", "small", "medium", "large", "turbo"]--# Load specific model-model = whisper.load_model("turbo") # Fastest, good quality-```--| Model | Parameters | English-only | Multilingual | Speed | VRAM |-|-------|------------|--------------|--------------|-------|------|-| tiny | 39M | ✓ | ✓ | ~32x | ~1 GB |-| base | 74M | ✓ | ✓ | ~16x | ~1 GB |-| small | 244M | ✓ | ✓ | ~6x | ~2 GB |-| medium | 769M | ✓ | ✓ | ~2x | ~5 GB |-| large | 1550M | ✗ | ✓ | 1x | ~10 GB |-| turbo | 809M | ✗ | ✓ | ~8x | ~6 GB |--**Recommendation**: Use `turbo` for best speed/quality, `base` for prototyping--## Transcription options--### Language specification--```python-# Auto-detect language-result = model.transcribe("audio.mp3")--# Specify language (faster)-result = model.transcribe("audio.mp3", language="en")--# Supported: en, es, fr, de, it, pt, ru, ja, ko, zh, and 89 more-```--### Task selection--```python-# Transcription (default)-result = model.transcribe("audio.mp3", task="transcribe")--# Translation to English-result = model.transcribe("spanish.mp3", task="translate")-# Input: Spanish audio → Output: English text-```--### Initial prompt--```python-# Improve accuracy with context-result = model.transcribe(- "audio.mp3",- initial_prompt="This is a technical podcast about machine learning and AI."-)--# Helps with:-# - Technical terms-# - Proper nouns-# - Domain-specific vocabulary-```--### Timestamps--```python-# Word-level timestamps-result = model.transcribe("audio.mp3", word_timestamps=True)--for segment in result["segments"]:- for word in segment["words"]:- print(f"{word['word']} ({word['start']:.2f}s - {word['end']:.2f}s)")-```--### Temperature fallback--```python-# Retry with different temperatures if confidence low-result = model.transcribe(- "audio.mp3",- temperature=(0.0, 0.2, 0.4, 0.6, 0.8, 1.0)-)-```--## Command line usage--```bash-# Basic transcription-whisper audio.mp3--# Specify model-whisper audio.mp3 --model turbo--# Output formats-whisper audio.mp3 --output_format txt # Plain text-whisper audio.mp3 --output_format srt # Subtitles-whisper audio.mp3 --output_format vtt # WebVTT-whisper audio.mp3 --output_format json # JSON with timestamps--# Language-whisper audio.mp3 --language Spanish--# Translation-whisper spanish.mp3 --task translate-```--## Batch processing--```python-import os--audio_files = ["file1.mp3", "file2.mp3", "file3.mp3"]--for audio_file in audio_files:- print(f"Transcribing {audio_file}...")- result = model.transcribe(audio_file)-- # Save to file- output_file = audio_file.replace(".mp3", ".txt")- with open(output_file, "w") as f:- f.write(result["text"])-```--## Real-time transcription--```python-# For streaming audio, use faster-whisper-# pip install faster-whisper--from faster_whisper import WhisperModel--model = WhisperModel("base", device="cuda", compute_type="float16")--# Transcribe with streaming-segments, info = model.transcribe("audio.mp3", beam_size=5)--for segment in segments:- print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")-```--## GPU acceleration--```python-import whisper--# Automatically uses GPU if available-model = whisper.load_model("turbo")--# Force CPU-model = whisper.load_model("turbo", device="cpu")--# Force GPU-model = whisper.load_model("turbo", device="cuda")--# 10-20× faster on GPU-```--## Integration with other tools--### Subtitle generation--```bash-# Generate SRT subtitles-whisper video.mp4 --output_format srt --language English--# Output: video.srt-```--### With LangChain--```python-from langchain.document_loaders import WhisperTranscriptionLoader--loader = WhisperTranscriptionLoader(file_path="audio.mp3")-docs = loader.load()--# Use transcription in RAG-from langchain_chroma import Chroma-from langchain_openai import OpenAIEmbeddings--vectorstore = Chroma.from_documents(docs, OpenAIEmbeddings())-```--### Extract audio from video--```bash-# Use ffmpeg to extract audio-ffmpeg -i video.mp4 -vn -acodec pcm_s16le audio.wav--# Then transcribe-whisper audio.wav-```--## Best practices--1. **Use turbo model** - Best speed/quality for English-2. **Specify language** - Faster than auto-detect-3. **Add initial prompt** - Improves technical terms-4. **Use GPU** - 10-20× faster-5. **Batch process** - More efficient-6. **Convert to WAV** - Better compatibility-7. **Split long audio** - <30 min chunks-8. **Check language support** - Quality varies by language-9. **Use faster-whisper** - 4× faster than openai-whisper-10. **Monitor VRAM** - Scale model size to hardware--## Performance--| Model | Real-time factor (CPU) | Real-time factor (GPU) |-|-------|------------------------|------------------------|-| tiny | ~0.32 | ~0.01 |-| base | ~0.16 | ~0.01 |-| turbo | ~0.08 | ~0.01 |-| large | ~1.0 | ~0.05 |--*Real-time factor: 0.1 = 10× faster than real-time*--## Language support--Top-supported languages:-- English (en)-- Spanish (es)-- French (fr)-- German (de)-- Italian (it)-- Portuguese (pt)-- Russian (ru)-- Japanese (ja)-- Korean (ko)-- Chinese (zh)--Full list: 99 languages total--## Limitations--1. **Hallucinations** - May repeat or invent text-2. **Long-form accuracy** - Degrades on >30 min audio-3. **Speaker identification** - No diarization-4. **Accents** - Quality varies-5. **Background noise** - Can affect accuracy-6. **Real-time latency** - Not suitable for live captioning--## Resources--- **GitHub**: https://github.com/openai/whisper ⭐ 72,900+-- **Paper**: https://arxiv.org/abs/2212.04356-- **Model Card**: https://github.com/openai/whisper/blob/main/model-card.md-- **Colab**: Available in repo-- **License**: MITdiff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md b/website/docs/user-guide/skills/optional/productivity/productivity-airtable.mdsimilarity index 98%rename from website/docs/user-guide/skills/bundled/productivity/productivity-airtable.mdrename to website/docs/user-guide/skills/optional/productivity/productivity-airtable.mdindex 3166b0a6738..75ea68c20cf 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md+++ b/website/docs/user-guide/skills/optional/productivity/productivity-airtable.md@@ -14,8 +14,8 @@ Airtable REST API via curl. Records CRUD, filters, upserts.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/airtable` |+| Source | Optional — install with `hermes skills install official/productivity/airtable` |+| Path | `optional-skills/productivity/airtable` || Version | `1.1.0` || Author | community || License | MIT |diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md b/website/docs/user-guide/skills/optional/productivity/productivity-box.mdsimilarity index 83%rename from website/docs/user-guide/skills/bundled/productivity/productivity-box.mdrename to website/docs/user-guide/skills/optional/productivity/productivity-box.mdindex 6f4620becb2..e3ba0f0b88b 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md+++ b/website/docs/user-guide/skills/optional/productivity/productivity-box.md@@ -14,8 +14,8 @@ Box manages cloud files, sharing, search, and metadata.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/box` |+| Source | Optional — install with `hermes skills install official/productivity/box` |+| Path | `optional-skills/productivity/box` || Version | `1.0.0` || Author | Chris Kim (iskysun96), Hermes Agent || License | MIT |@@ -55,24 +55,24 @@ Start normal CLI work with the official Box CLI OAuth app. It covers ordinary coWhen a user selects an authentication path or asks Hermes to connect Box, perform the setup through `terminal`; do not turn the next response into instructions for the user to copy. Take the next safe action yourself, and pause only for an approval, browser sign-in, administrator action, or secret that Hermes cannot safely supply.-- If `box` is missing, ask for any terminal approval required to install `@box/cli` under the current Hermes home at `tools/box-cli`; then verify it with the shell-appropriate command in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md). Do not attempt a global npm install, use `sudo`, change npm's global prefix, or change `PATH`.-- Before OAuth, ask: **“Is Hermes running on the same computer as the browser you will use to authorize Box, or on a remote host such as a VPS, container, or cloud VM?”** Use normal `box login` only for the same-computer path. Use `box login --code` only for the remote/headless path. Do not infer runtime topology from the operating system alone; read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/oauth-setup.md) after the user answers.+- If `box` is missing, ask for any terminal approval required to install `@box/cli` under the current Hermes home at `tools/box-cli`; then verify it with the shell-appropriate command in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/cli-guide.md). Do not attempt a global npm install, use `sudo`, change npm's global prefix, or change `PATH`.+- Before OAuth, ask: **“Is Hermes running on the same computer as the browser you will use to authorize Box, or on a remote host such as a VPS, container, or cloud VM?”** Use normal `box login` only for the same-computer path. Use `box login --code` only for the remote/headless path. Do not infer runtime topology from the operating system alone; read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/oauth-setup.md) after the user answers.- Before starting browser authorization, state that Hermes will act as the Box account signed in there. If the user wants narrower access, they can authorize an account that is invited only to the required files, folders, or Hubs. Do not make that account an administrator to unlock an exceptional operation.- If a custom OAuth Platform App is necessary, use the CLI's interactive Platform App flow. Ask the user to enter its client secret only in the local CLI prompt; never request it in chat, write it to Hermes configuration, or commit it.- If an install, browser authorization, environment switch, or permission change needs approval, request that approval and resume the setup after it is granted. Do not replace the action with a command list.## Start each task-1. Confirm the CLI and current actor. Probe with `command -v box` on POSIX shells or `Get-Command box -ErrorAction SilentlyContinue` in PowerShell. If `box` is on `PATH`, use it. If Hermes installed the CLI under its current home, use the shell-appropriate verified runner in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md) in place of every leading `box`. Then run `box users:get me --json --fields id,name,login` with that runner.- If this succeeds, record the actor and continue. Do not ask about authentication again. Treat `folders:items 0` only as a listing of the actor's root; it is not proof that a shared file, folder, or Hub is inaccessible. For a known file or folder, verify its ID directly; for a Hub, use the Hubs discovery path in [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md).-2. If authentication is absent, ask to connect a Box account with OAuth, then ask whether Hermes and the authorization browser run on the same computer or on separate hosts. Read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/oauth-setup.md).+1. Confirm the CLI and current actor. Probe with `command -v box` on POSIX shells or `Get-Command box -ErrorAction SilentlyContinue` in PowerShell. If `box` is on `PATH`, use it. If Hermes installed the CLI under its current home, use the shell-appropriate verified runner in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/cli-guide.md) in place of every leading `box`. Then run `box users:get me --json --fields id,name,login` with that runner.+ If this succeeds, record the actor and continue. Do not ask about authentication again. Treat `folders:items 0` only as a listing of the actor's root; it is not proof that a shared file, folder, or Hub is inaccessible. For a known file or folder, verify its ID directly; for a Hub, use the Hubs discovery path in [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/hubs.md).+2. If authentication is absent, ask to connect a Box account with OAuth, then ask whether Hermes and the authorization browser run on the same computer or on separate hosts. Read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/oauth-setup.md).3. Read the relevant reference before operating. Use documented commands first; only run subcommand help when the request needs an option not covered by the reference or the installed CLI rejects the documented form.Examples labeled `bash` use POSIX continuation syntax. In PowerShell, run the Box command on one line or replace each trailing `\` with PowerShell's backtick continuation. Do not paste POSIX variable assignments into PowerShell.## Extend the CLI without pausing-When the Box CLI lacks a dedicated subcommand, use `box request` for the matching REST endpoint and continue the ordinary operation. Do not ask the user to choose merely because the implementation uses REST; it is the same Box task and preserves the configured CLI identity. Read [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/rest-api.md) when the endpoint needs a request body or custom header.+When the Box CLI lacks a dedicated subcommand, use `box request` for the matching REST endpoint and continue the ordinary operation. Do not ask the user to choose merely because the implementation uses REST; it is the same Box task and preserves the configured CLI identity. Read [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/rest-api.md) when the endpoint needs a request body or custom header.Ask before a delete, a collaboration/shared-link or permission change, an identity change, a broad or costly batch mutation, or when the target or scope is ambiguous. Otherwise perform the requested operation and verify it.@@ -80,15 +80,15 @@ Ask before a delete, a collaboration/shared-link or permission change, an identi| Need | Read || --- | --- |-| CLI conventions, environments, JSON, or REST escape hatch | [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md) |-| Files, folders, versions, links, or collaborations | [Content workflows](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/content-workflows.md) |-| Search, metadata, Box AI, or AI units | [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md) |-| Curated large-scale Q&A or a reusable knowledge base | [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md) |-| Many files or a resumable batch | [Bulk operations](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/bulk-operations.md) |-| Application code or a Box SDK | [SDK development](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/sdk-development.md) |-| Webhooks or Events API | [Webhooks and events](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/webhooks-and-events.md) |-| CLI unavailable or a missing CLI operation | [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/rest-api.md) |-| Auth, permissions, rate limits, or API errors | [Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/troubleshooting.md) |+| CLI conventions, environments, JSON, or REST escape hatch | [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/cli-guide.md) |+| Files, folders, versions, links, or collaborations | [Content workflows](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/content-workflows.md) |+| Search, metadata, Box AI, or AI units | [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/search-and-ai.md) |+| Curated large-scale Q&A or a reusable knowledge base | [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/hubs.md) |+| Many files or a resumable batch | [Bulk operations](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/bulk-operations.md) |+| Application code or a Box SDK | [SDK development](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/sdk-development.md) |+| Webhooks or Events API | [Webhooks and events](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/webhooks-and-events.md) |+| CLI unavailable or a missing CLI operation | [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/rest-api.md) |+| Auth, permissions, rate limits, or API errors | [Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/troubleshooting.md) |## Content handling policy@@ -101,13 +101,13 @@ Use existing Box metadata or metadata queries for deterministic lookups. Otherwi- `ai:extract` for flexible key-value extraction- `ai:text-gen` for writing grounded in one Box file-For Q&A over more than 25 files or a reusable curated knowledge base, prefer Box AI for Hubs. Discover an existing accessible Hub first; only create or populate one after the user approves the shared-resource change. If no Hub is available and the user does not want one created, narrow a one-off request with search or metadata. Do not use a Hub for metadata extraction or text generation. Read [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md).+For Q&A over more than 25 files or a reusable curated knowledge base, prefer Box AI for Hubs. Discover an existing accessible Hub first; only create or populate one after the user approves the shared-resource change. If no Hub is available and the user does not want one created, narrow a one-off request with search or metadata. Do not use a Hub for metadata extraction or text generation. Read [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/hubs.md).When the user asks to extract metadata from a Box file, treat it as a request to persist the result unless they ask for a preview. Use structured extraction with inline fields when the desired schema is known and freeform extraction when the fields are exploratory. Reuse a compatible existing enterprise template when one represents every requested field. Otherwise store flat scalar results in the built-in `global.properties` metadata instance, or upload a JSON sidecar beside the source file when the result contains nested objects, tables, or values that must retain their types. Read every write back and compare it with the intended result. Never silently substitute a file description, attach a partial or unrelated template, truncate fields, or discard fields.-Do not create or change metadata templates. Box does not permit creation of global templates, and enterprise-template administration is outside Hermes' normal OAuth content workflow. If the user needs reusable typed enterprise metadata and no compatible template exists, explain that a Box Admin or authorized Co-Admin must create it separately, leave existing structured metadata unchanged, and report the persisted `global.properties` instance or JSON sidecar instead. Read [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md) for the complete extraction and writeback workflow.+Do not create or change metadata templates. Box does not permit creation of global templates, and enterprise-template administration is outside Hermes' normal OAuth content workflow. If the user needs reusable typed enterprise metadata and no compatible template exists, explain that a Box Admin or authorized Co-Admin must create it separately, leave existing structured metadata unchanged, and report the persisted `global.properties` instance or JSON sidecar instead. Read [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/search-and-ai.md) for the complete extraction and writeback workflow.-Before the first Box AI request, state that Box AI must be enabled, consumes AI units, and remains limited to the current actor's permissions; do not wait for acknowledgement. An AI response returned to Hermes can still contain sensitive information. Confirm only when a material batch's file scope or expected AI-unit use is ambiguous, or when the user has not explicitly requested that scale. See [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md).+Before the first Box AI request, state that Box AI must be enabled, consumes AI units, and remains limited to the current actor's permissions; do not wait for acknowledgement. An AI response returned to Hermes can still contain sensitive information. Confirm only when a material batch's file scope or expected AI-unit use is ambiguous, or when the user has not explicitly requested that scale. See [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/productivity/box/references/search-and-ai.md).## Operate safelydiff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md b/website/docs/user-guide/skills/optional/productivity/productivity-notion.mdsimilarity index 99%rename from website/docs/user-guide/skills/bundled/productivity/productivity-notion.mdrename to website/docs/user-guide/skills/optional/productivity/productivity-notion.mdindex b198d73f60c..56a2627004a 100644--- a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md+++ b/website/docs/user-guide/skills/optional/productivity/productivity-notion.md@@ -14,8 +14,8 @@ Notion API + ntn CLI: pages, databases, markdown, Workers.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/productivity/notion` |+| Source | Optional — install with `hermes skills install official/productivity/notion` |+| Path | `optional-skills/productivity/notion` || Version | `2.0.0` || Author | community || License | MIT |diff --git a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.mdindex 9b718d69479..6ea97dd0dc6 100644--- a/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md+++ b/website/docs/user-guide/skills/optional/productivity/productivity-shopify.md@@ -21,7 +21,7 @@ Query Shopify Admin/Storefront GraphQL APIs via curl.| License | MIT || Platforms | linux, macos, windows || Tags | `Shopify`, `E-commerce`, `Commerce`, `API`, `GraphQL` |-| Related skills | [`airtable`](../../bundled/productivity/productivity-airtable.md), [`xurl`](../../bundled/social-media/social-media-xurl.md) |+| Related skills | [`airtable`](../../optional/productivity/productivity-airtable.md), [`xurl`](../../bundled/social-media/social-media-xurl.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.mdindex 7451ee8d71f..242ac1619ba 100644--- a/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md+++ b/website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md@@ -21,7 +21,7 @@ Query and edit a SiYuan knowledge base via its API.| License | MIT || Platforms | linux, macos, windows || Tags | `SiYuan`, `Notes`, `Knowledge Base`, `PKM`, `API` |-| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`notion`](../../bundled/productivity/productivity-notion.md) |+| Related skills | [`obsidian`](../../bundled/note-taking/note-taking-obsidian.md), [`notion`](../../optional/productivity/productivity-notion.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md b/website/docs/user-guide/skills/optional/research/research-llm-wiki.mdsimilarity index 99%rename from website/docs/user-guide/skills/bundled/research/research-llm-wiki.mdrename to website/docs/user-guide/skills/optional/research/research-llm-wiki.mdindex b449baadfde..8f79702f7ae 100644--- a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md+++ b/website/docs/user-guide/skills/optional/research/research-llm-wiki.md@@ -14,8 +14,8 @@ Karpathy's LLM Wiki: build/query interlinked markdown KB.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/research/llm-wiki` |+| Source | Optional — install with `hermes skills install official/research/llm-wiki` |+| Path | `optional-skills/research/llm-wiki` || Version | `2.1.0` || Author | Hermes Agent || License | MIT |diff --git a/website/docs/user-guide/skills/optional/research/research-pinecone-research.md b/website/docs/user-guide/skills/optional/research/research-pinecone-research.mddeleted file mode 100644index dd6a9eb0796..00000000000--- a/website/docs/user-guide/skills/optional/research/research-pinecone-research.md+++ /dev/null@@ -1,125 +0,0 @@-----title: "Pinecone Research — Agent RAG and long-term memory with Pinecone"-sidebar_label: "Pinecone Research"-description: "Agent RAG and long-term memory with Pinecone"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Pinecone Research--Agent RAG and long-term memory with Pinecone.--## Skill metadata--| | |-|---|---|-| Source | Optional — install with `hermes skills install official/research/pinecone-research` |-| Path | `optional-skills/research/pinecone-research` |-| Version | `1.0.0` |-| Author | immuhammadfurqan |-| License | MIT |-| Dependencies | `pinecone-client`, `langchain-pinecone` |-| Platforms | linux, macos, windows |-| Tags | `RAG`, `Pinecone`, `Memory`, `Research`, `Vector Database`, `Agent`, `Retrieval` |--## Reference: full SKILL.md--:::info-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.-:::--# Pinecone Research — Agent RAG & Long-Term Memory--Use Pinecone as a retrieval-augmented generation (RAG) backend for agent-conversations: persist embeddings, retrieve relevant context from past-sessions, and build long-term memory.--## When to use this skill--**Use when:**-- Building agent RAG pipelines with Pinecone as the vector store-- Need persistent long-term memory across agent sessions-- Combining retrieval with agent tool use-- Researching or prototyping semantic search workflows--**Use the mlops/pinecone skill instead when:**-- Need a general Pinecone reference (index management, CRUD, hybrid search)-- Working on production infrastructure without agent integration--## Quick start--### Setup--```bash-pip install pinecone-client langchain-pinecone langchain-openai-```--Set your API key:-```bash-export PINECONE_API_KEY="your-api-key"-```--### Basic RAG pipeline--```python-from pinecone import Pinecone, ServerlessSpec-from langchain_pinecone import PineconeVectorStore-from langchain_openai import OpenAIEmbeddings--# Initialize Pinecone-pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])--# Create or connect to index-index_name = "agent-memory"-if index_name not in [i.name for i in pc.list_indexes()]:- pc.create_index(- name=index_name,- dimension=1536,- metric="cosine",- spec=ServerlessSpec(cloud="aws", region="us-east-1"),- )--# Build vector store-vectorstore = PineconeVectorStore.from_documents(- documents=docs,- embedding=OpenAIEmbeddings(),- index_name=index_name,-)--# Retrieve relevant context-retriever = vectorstore.as_retriever(search_kwargs={"k": 5})-results = retriever.invoke("What did the agent discuss yesterday?")-```--### Namespace-based session memory--```python-# Store per-session memory-vectorstore = PineconeVectorStore(- index=pc.Index(index_name),- embedding=OpenAIEmbeddings(),- namespace=f"session-{session_id}",-)--# Query across all sessions (no namespace filter)-all_memory = PineconeVectorStore(- index=pc.Index(index_name),- embedding=OpenAIEmbeddings(),-)-results = all_memory.similarity_search("relevant query", k=10)-```--## Best practices--1. **Namespace by session or user** — isolate data for multi-tenant agents-2. **Batch upserts** — 100–200 vectors per batch for efficiency-3. **Metadata filtering** — tag vectors with session ID, timestamp, topic-4. **Prune old memory** — delete stale namespaces to control costs-5. **Use serverless** — auto-scaling, pay-per-use pricing--## Resources--- **Pinecone Docs**: https://docs.pinecone.io-- **LangChain Integration**: https://python.langchain.com/docs/integrations/vectorstores/pinecone-- **Free Tier**: 1 index, 100K vectors (1536 dimensions)diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/optional/software-development/software-development-hermes-agent-skill-authoring.mdsimilarity index 98%rename from website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.mdrename to website/docs/user-guide/skills/optional/software-development/software-development-hermes-agent-skill-authoring.mdindex cc363d7d7df..1bd4ecea0ed 100644--- a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md+++ b/website/docs/user-guide/skills/optional/software-development/software-development-hermes-agent-skill-authoring.md@@ -14,8 +14,8 @@ Author in-repo SKILL.md files: frontmatter and structure.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/software-development/hermes-agent-skill-authoring` |+| Source | Optional — install with `hermes skills install official/software-development/hermes-agent-skill-authoring` |+| Path | `optional-skills/software-development/hermes-agent-skill-authoring` || Version | `2.0.0` || Author | Hermes Agent || License | MIT |diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md b/website/docs/user-guide/skills/optional/software-development/software-development-inspecting-hermes-desktop-dom.mdsimilarity index 92%rename from website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.mdrename to website/docs/user-guide/skills/optional/software-development/software-development-inspecting-hermes-desktop-dom.mdindex 516f42bbb93..5ae1f73c16e 100644--- a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md+++ b/website/docs/user-guide/skills/optional/software-development/software-development-inspecting-hermes-desktop-dom.md@@ -14,14 +14,14 @@ Read the live Hermes desktop DOM/CSS over CDP.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/software-development/inspecting-hermes-desktop-dom` |+| Source | Optional — install with `hermes skills install official/software-development/inspecting-hermes-desktop-dom` |+| Path | `optional-skills/software-development/inspecting-hermes-desktop-dom` || Version | `1.0.0` || Author | Hermes Agent || License | MIT || Platforms | linux, macos, windows || Tags | `desktop`, `electron`, `cdp`, `dom`, `ui-verification`, `self-inspection` |-| Related skills | [`node-inspect-debugger`](../../bundled/software-development/software-development-node-inspect-debugger.md), [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`dogfood`](../../bundled/software-development/software-development-dogfood.md) |+| Related skills | [`node-inspect-debugger`](../../optional/software-development/software-development-node-inspect-debugger.md), [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`dogfood`](../../bundled/software-development/software-development-dogfood.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/docs/user-guide/skills/optional/software-development/software-development-node-inspect-debugger.mdsimilarity index 97%rename from website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.mdrename to website/docs/user-guide/skills/optional/software-development/software-development-node-inspect-debugger.mdindex 90fd243bce8..57bdc0cc3b3 100644--- a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md+++ b/website/docs/user-guide/skills/optional/software-development/software-development-node-inspect-debugger.md@@ -14,14 +14,14 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/software-development/node-inspect-debugger` |+| Source | Optional — install with `hermes skills install official/software-development/node-inspect-debugger` |+| Path | `optional-skills/software-development/node-inspect-debugger` || Version | `1.0.0` || Author | Hermes Agent || License | MIT || Platforms | linux, macos, windows || Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |-| Related skills | [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`python-debugpy`](../../bundled/software-development/software-development-python-debugpy.md) |+| Related skills | [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`python-debugpy`](../../optional/software-development/software-development-python-debugpy.md) |## Reference: full SKILL.mddiff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/docs/user-guide/skills/optional/software-development/software-development-python-debugpy.mdsimilarity index 98%rename from website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.mdrename to website/docs/user-guide/skills/optional/software-development/software-development-python-debugpy.mdindex d0d8fe7b4b7..78c5b7ba502 100644--- a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md+++ b/website/docs/user-guide/skills/optional/software-development/software-development-python-debugpy.md@@ -14,14 +14,14 @@ Debug Python: pdb REPL + debugpy remote (DAP).| | ||---|---|-| Source | Bundled (installed by default) |-| Path | `skills/software-development/python-debugpy` |+| Source | Optional — install with `hermes skills install official/software-development/python-debugpy` |+| Path | `optional-skills/software-development/python-debugpy` || Version | `1.0.0` || Author | Hermes Agent || License | MIT || Platforms | linux, macos || Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |-| Related skills | [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`node-inspect-debugger`](../../bundled/software-development/software-development-node-inspect-debugger.md) |+| Related skills | [`systematic-debugging`](../../bundled/software-development/software-development-systematic-debugging.md), [`node-inspect-debugger`](../../optional/software-development/software-development-node-inspect-debugger.md) |## Reference: full SKILL.mddiff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.mddeleted file mode 100644index fd0af980a40..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md+++ /dev/null@@ -1,237 +0,0 @@-----title: "Opencode — 将编码任务委托给 OpenCode CLI(功能开发、PR 审查)"-sidebar_label: "Opencode"-description: "将编码任务委托给 OpenCode CLI(功能开发、PR 审查)"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Opencode--将编码任务委托给 OpenCode CLI(功能开发、PR 审查)。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/autonomous-ai-agents/opencode` |-| 版本 | `1.2.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |-| 相关 skill | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# OpenCode CLI--使用 [OpenCode](https://opencode.ai) 作为由 Hermes 终端/进程工具编排的自主编码工作器。OpenCode 是一个支持多 provider、开源的 AI 编码 agent,具备 TUI(终端用户界面)和 CLI。--## 适用场景--- 用户明确要求使用 OpenCode-- 需要外部编码 agent 来实现/重构/审查代码-- 需要长时间运行的编码会话并定期检查进度-- 需要在隔离的工作目录/worktree 中并行执行任务--## 前置条件--- 已安装 OpenCode:`npm i -g opencode-ai@latest` 或 `brew install anomalyco/tap/opencode`-- 已配置认证:`opencode auth login` 或设置 provider 环境变量(OPENROUTER_API_KEY 等)-- 验证:`opencode auth list` 应显示至少一个 provider-- 代码任务推荐使用 Git 仓库-- 交互式 TUI 会话需要 `pty=true`--## 二进制文件解析(重要)--Shell 环境可能会解析到不同的 OpenCode 二进制文件。如果你的终端与 Hermes 的行为不一致,请检查:--```-terminal(command="which -a opencode")-terminal(command="opencode --version")-```--如有需要,可固定使用明确的二进制路径:--```-terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)-```--## 单次任务--使用 `opencode run` 执行有边界的非交互式任务:--```-terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")-```--使用 `-f` 附加上下文文件:--```-terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")-```--使用 `--thinking` 显示模型思考过程:--```-terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")-```--强制指定特定模型:--```-terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")-```--## 交互式会话(后台运行)--对于需要多轮交互的迭代工作,在后台启动 TUI:--```-terminal(command="opencode", workdir="~/project", background=true, pty=true)-# 返回 session_id--# 发送 prompt(提示词)-process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")--# 监控进度-process(action="poll", session_id="<id>")-process(action="log", session_id="<id>")--# 发送后续输入-process(action="submit", session_id="<id>", data="Now add error handling for token expiry")--# 干净退出 — Ctrl+C-process(action="write", session_id="<id>", data="\x03")-# 或直接终止进程-process(action="kill", session_id="<id>")-```--**重要:** 不要使用 `/exit`——它不是有效的 OpenCode 命令,会打开 agent 选择器对话框。请使用 Ctrl+C(`\x03`)或 `process(action="kill")` 退出。--### TUI 快捷键--| 按键 | 操作 |-|-----|--------|-| `Enter` | 提交消息(如有需要可按两次) |-| `Tab` | 在 agent 之间切换(build/plan) |-| `Ctrl+P` | 打开命令面板 |-| `Ctrl+X L` | 切换会话 |-| `Ctrl+X M` | 切换模型 |-| `Ctrl+X N` | 新建会话 |-| `Ctrl+X E` | 打开编辑器 |-| `Ctrl+C` | 退出 OpenCode |--### 恢复会话--退出后,OpenCode 会打印会话 ID。使用以下命令恢复:--```-terminal(command="opencode -c", workdir="~/project", background=true, pty=true) # 继续上次会话-terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true) # 指定会话-```--## 常用标志--| 标志 | 用途 |-|------|-----|-| `run 'prompt'` | 单次执行后退出 |-| `--continue` / `-c` | 继续上次 OpenCode 会话 |-| `--session <id>` / `-s` | 继续指定会话 |-| `--agent <name>` | 选择 OpenCode agent(build 或 plan) |-| `--model provider/model` | 强制使用指定模型 |-| `--format json` | 机器可读的输出/事件 |-| `--file <path>` / `-f` | 向消息附加文件 |-| `--thinking` | 显示模型思考块 |-| `--variant <level>` | 推理强度(high、max、minimal) |-| `--title <name>` | 为会话命名 |-| `--attach <url>` | 连接到正在运行的 opencode 服务器 |--## 操作流程--1. 验证工具就绪状态:- - `terminal(command="opencode --version")`- - `terminal(command="opencode auth list")`-2. 对于有边界的任务,使用 `opencode run '...'`(无需 pty)。-3. 对于迭代任务,使用 `background=true, pty=true` 启动 `opencode`。-4. 使用 `process(action="poll"|"log")` 监控长时间运行的任务。-5. 如果 OpenCode 请求输入,通过 `process(action="submit", ...)` 响应。-6. 使用 `process(action="write", data="\x03")` 或 `process(action="kill")` 退出,切勿使用 `/exit`。-7. 向用户汇总文件变更、测试结果及后续步骤。--## PR 审查工作流--OpenCode 内置 PR 命令:--```-terminal(command="opencode pr 42", workdir="~/project", pty=true)-```--或在临时克隆中审查以实现隔离:--```-terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)-```--## 并行工作模式--使用独立的工作目录/worktree 避免冲突:--```-terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)-terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)-process(action="list")-```--## 会话与成本管理--列出历史会话:--```-terminal(command="opencode session list")-```--查看 token 用量和费用:--```-terminal(command="opencode stats")-terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")-```--## 注意事项--- 交互式 `opencode`(TUI)会话需要 `pty=true`。`opencode run` 命令**不需要** pty。-- `/exit` **不是**有效命令——它会打开 agent 选择器。请使用 Ctrl+C 退出 TUI。-- PATH 不匹配可能导致选择错误的 OpenCode 二进制文件/模型配置。-- 如果 OpenCode 看起来卡住了,在终止前先检查日志:- - `process(action="log", session_id="<id>")`-- 避免多个并行 OpenCode 会话共享同一工作目录。-- 在 TUI 中可能需要按两次 Enter 才能提交(第一次确认文本,第二次发送)。--## 验证--冒烟测试:--```-terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")-```--成功标准:-- 输出包含 `OPENCODE_SMOKE_OK`-- 命令退出时无 provider/模型错误-- 对于代码任务:预期文件已变更且测试通过--## 规则--1. 单次自动化任务优先使用 `opencode run`——更简单且无需 pty。-2. 仅在需要迭代时使用交互式后台模式。-3. 始终将 OpenCode 会话限定在单个仓库/工作目录内。-4. 对于长时间任务,从 `process` 日志中提供进度更新。-5. 报告具体结果(文件变更、测试情况、剩余风险)。-6. 使用 Ctrl+C 或 kill 退出交互式会话,切勿使用 `/exit`。\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-design-md.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-design-md.mddeleted file mode 100644index 4d21eb7f671..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-design-md.md+++ /dev/null@@ -1,189 +0,0 @@-----title: "Design Md — 编写/验证/导出 Google 的 DESIGN"-sidebar_label: "Design Md"-description: "编写/验证/导出 Google 的 DESIGN"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Design Md--编写/验证/导出 Google 的 DESIGN.md token(设计令牌)规范文件。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/creative/design-md` |-| 版本 | `1.0.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |-| 相关 skill | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# DESIGN.md Skill--DESIGN.md 是 Google 的开放规范(Apache-2.0,`google-labs-code/design.md`),用于向编码 agent 描述视觉标识。一个文件包含:--- **YAML 前置元数据** — 机器可读的设计 token(规范值)-- **Markdown 正文** — 人类可读的说明,按规范章节组织--Token 提供精确值。正文告诉 agent *为什么*这些值存在以及如何应用它们。CLI(`npx @google/design.md`)可对结构和 WCAG 对比度进行 lint 检查,对版本进行 diff 以检测回归,并导出为 Tailwind 或 W3C DTCG JSON。--## 何时使用此 skill--- 用户请求 DESIGN.md 文件、设计 token 或设计系统规范-- 用户希望在多个项目或工具中保持一致的 UI/品牌风格-- 用户粘贴了现有的 DESIGN.md,并要求进行 lint、diff、导出或扩展-- 用户希望将样式指南移植为 agent 可消费的格式-- 用户希望对其调色板进行对比度/WCAG 无障碍验证--若仅需视觉灵感或布局示例,请改用 `popular-web-designs`。若需要从零开始设计一次性 HTML 产物(原型、幻灯片、落地页、组件实验室)时的*流程与品味*,请使用 `claude-design`。本 skill 专用于*正式规范文件*本身。--## 文件结构--```md-----version: alpha-name: Heritage-description: Architectural minimalism meets journalistic gravitas.-colors:- primary: "#1A1C1E"- secondary: "#6C7278"- tertiary: "#B8422E"- neutral: "#F7F5F2"-typography:- h1:- fontFamily: Public Sans- fontSize: 3rem- fontWeight: 700- lineHeight: 1.1- letterSpacing: "-0.02em"- body-md:- fontFamily: Public Sans- fontSize: 1rem-rounded:- sm: 4px- md: 8px- lg: 16px-spacing:- sm: 8px- md: 16px- lg: 24px-components:- button-primary:- backgroundColor: "{colors.tertiary}"- textColor: "#FFFFFF"- rounded: "{rounded.sm}"- padding: 12px- button-primary-hover:- backgroundColor: "{colors.primary}"------## Overview--Architectural Minimalism meets Journalistic Gravitas...--## Colors--- **Primary (#1A1C1E):** Deep ink for headlines and core text.-- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.--## Typography--Public Sans for everything except small all-caps labels...--## Components--`button-primary` is the only high-emphasis action on a page...-```--## Token 类型--| 类型 | 格式 | 示例 |-|------|--------|---------|-| 颜色 | `#` + 十六进制(sRGB) | `"#1A1C1E"` |-| 尺寸 | 数字 + 单位(`px`、`em`、`rem`) | `48px`、`-0.02em` |-| Token 引用 | `{path.to.token}` | `{colors.primary}` |-| 字体排版 | 包含 `fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`、`fontFeature`、`fontVariation` 的对象 | 见上方 |--组件属性白名单:`backgroundColor`、`textColor`、`typography`、`rounded`、`padding`、`size`、`height`、`width`。变体(hover、active、pressed)是**独立的组件条目**,使用相关键名(`button-primary-hover`),而非嵌套结构。--## 规范章节顺序--章节均为可选,但已存在的章节**必须**按以下顺序排列。重复标题将导致文件被拒绝。--1. Overview(别名:Brand & Style)-2. Colors-3. Typography-4. Layout(别名:Layout & Spacing)-5. Elevation & Depth(别名:Elevation)-6. Shapes-7. Components-8. Do's and Don'ts--未知章节会被保留,不会报错。未知 token 名称在值类型有效时可被接受。未知组件属性会产生警告。--## 工作流:编写新的 DESIGN.md--1. **询问用户**(或推断)品牌基调、强调色和字体方向。若用户提供了网站、图片或风格描述,将其转换为上述 token 结构。-2. **编写 `DESIGN.md`**,使用 `write_file` 写入项目根目录。始终包含 `name:` 和 `colors:`;其他章节可选但建议添加。-3. **使用 token 引用**(`{colors.primary}`)在 `components:` 章节中引用颜色,而非重复输入十六进制值。保持调色板单一来源。-4. **进行 lint 检查**(见下文)。在返回前修复所有断开的引用或 WCAG 失败项。-5. **若用户有现有项目**,同时将 Tailwind 或 DTCG 导出文件写入文件旁(`tailwind.theme.json`、`tokens.json`)。--## 工作流:lint / diff / 导出--CLI 为 `@google/design.md`(Node)。使用 `npx`,无需全局安装。--```bash-# 验证结构 + token 引用 + WCAG 对比度-npx -y @google/design.md lint DESIGN.md--# 比较两个版本,发现回归时失败(exit 1 = 存在回归)-npx -y @google/design.md diff DESIGN.md DESIGN-v2.md--# 导出为 Tailwind 主题 JSON-npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json--# 导出为 W3C DTCG(Design Tokens Format Module)JSON-npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json--# 打印规范本身 — 在注入 agent prompt 时很有用-npx -y @google/design.md spec --rules-only --format json-```--所有命令均接受 `-` 作为 stdin。`lint` 在出现错误时返回 exit 1。若需要以结构化方式报告结果,请使用 `--format json` 标志并解析输出。--### Lint 规则参考(7 条规则的检查内容)--- `broken-ref`(错误)— `{colors.missing}` 指向不存在的 token-- `duplicate-section`(错误)— 同一 `## 标题` 出现两次-- `invalid-color`、`invalid-dimension`、`invalid-typography`(错误)-- `wcag-contrast`(警告/信息)— 组件 `textColor` 与 `backgroundColor` 的对比度,对照 WCAG AA(4.5:1)和 AAA(7:1)-- `unknown-component-property`(警告)— 超出上述白名单范围--当用户关注无障碍性时,请在摘要中明确指出 — WCAG 检查结果是使用 CLI 最重要的理由。--## 常见陷阱--- **不要嵌套组件变体。** `button-primary.hover` 是错误的;应将 `button-primary-hover` 作为同级键。-- **十六进制颜色必须加引号。** 否则 YAML 会在 `#` 处出错,或将 `#1A1C1E` 等值截断。-- **负数尺寸也需要加引号。** `letterSpacing: -0.02em` 会被解析为 YAML flow — 应写为 `letterSpacing: "-0.02em"`。-- **章节顺序是强制的。** 若用户以随机顺序提供正文,在保存前须重新排列为规范列表顺序。-- **`version: alpha` 是当前规范版本**(截至 2026 年 4 月)。该规范标记为 alpha — 请关注破坏性变更。-- **Token 引用通过点分路径解析。** `{colors.primary}` 有效;`{primary}` 无效。--## 规范来源--- 仓库:https://github.com/google-labs-code/design.md(Apache-2.0)-- CLI:npm 上的 `@google/design.md`-- 生成的 DESIGN.md 文件的许可证:取决于用户项目所使用的许可证;规范本身为 Apache-2.0。\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-gif-search.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-gif-search.mddeleted file mode 100644index 5d191fcbae8..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-gif-search.md+++ /dev/null@@ -1,106 +0,0 @@-----title: "Gif Search — 通过 curl + jq 搜索/下载 Tenor GIF"-sidebar_label: "Gif Search"-description: "通过 curl + jq 搜索/下载 Tenor GIF"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Gif Search--通过 curl + jq 搜索/下载 Tenor GIF。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/media/gif-search` |-| 版本 | `1.1.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `GIF`, `Media`, `Search`, `Tenor`, `API` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# GIF Search(Tenor API)--通过 Tenor API 使用 curl 直接搜索和下载 GIF,无需额外工具。--## 使用场景--适用于查找反应 GIF、创建视觉内容以及在聊天中发送 GIF。--## 配置--在环境中设置 Tenor API 密钥(添加到 `~/.hermes/.env`):--```bash-TENOR_API_KEY=your_key_here-```--在 https://developers.google.com/tenor/guides/quickstart 免费获取 API 密钥 —— Google Cloud Console Tenor API 密钥免费且具有较高的速率限制。--## 前置条件--- `curl` 和 `jq`(macOS/Linux 标准工具)-- `TENOR_API_KEY` 环境变量--## 搜索 GIF--```bash-# 搜索并获取 GIF URL-curl -s "https://tenor.googleapis.com/v2/search?q=thumbs+up&limit=5&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.gif.url'--# 获取较小的预览版本-curl -s "https://tenor.googleapis.com/v2/search?q=nice+work&limit=3&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.tinygif.url'-```--## 下载 GIF--```bash-# 搜索并下载排名第一的结果-URL=$(curl -s "https://tenor.googleapis.com/v2/search?q=celebration&limit=1&key=${TENOR_API_KEY}" | jq -r '.results[0].media_formats.gif.url')-curl -sL "$URL" -o celebration.gif-```--## 获取完整元数据--```bash-curl -s "https://tenor.googleapis.com/v2/search?q=cat&limit=3&key=${TENOR_API_KEY}" | jq '.results[] | {title: .title, url: .media_formats.gif.url, preview: .media_formats.tinygif.url, dimensions: .media_formats.gif.dims}'-```--## API 参数--| 参数 | 说明 |-|-----------|-------------|-| `q` | 搜索查询(空格用 `+` 进行 URL 编码) |-| `limit` | 最大结果数(1-50,默认 20) |-| `key` | API 密钥(来自 `$TENOR_API_KEY` 环境变量) |-| `media_filter` | 过滤格式:`gif`、`tinygif`、`mp4`、`tinymp4`、`webm` |-| `contentfilter` | 安全级别:`off`、`low`、`medium`、`high` |-| `locale` | 语言:`en_US`、`es`、`fr` 等 |--## 可用媒体格式--每个结果在 `.media_formats` 下包含多种格式:--| 格式 | 使用场景 |-|--------|----------|-| `gif` | 完整质量 GIF |-| `tinygif` | 小型预览 GIF |-| `mp4` | 视频版本(文件体积更小) |-| `tinymp4` | 小型预览视频 |-| `webm` | WebM 视频 |-| `nanogif` | 微型缩略图 |--## 注意事项--- 对查询进行 URL 编码:空格用 `+`,特殊字符用 `%XX`-- 在聊天中发送时,`tinygif` URL 更轻量-- GIF URL 可直接用于 markdown:``\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-songsee.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-songsee.mddeleted file mode 100644index f66fca746c9..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/media/media-songsee.md+++ /dev/null@@ -1,98 +0,0 @@-----title: "Songsee — 通过 CLI 生成音频频谱图/特征(mel、chroma、MFCC)"-sidebar_label: "Songsee"-description: "通过 CLI 生成音频频谱图/特征(mel、chroma、MFCC)"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Songsee--通过 CLI 生成音频频谱图/特征(mel、chroma、MFCC)。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/media/songsee` |-| 版本 | `1.0.0` |-| 作者 | community |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `Audio`, `Visualization`, `Spectrogram`, `Music`, `Analysis` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# songsee--从音频文件生成频谱图(spectrogram)及多面板音频特征可视化图。--## 前置条件--需要安装 [Go](https://go.dev/doc/install):-```bash-go install github.com/steipete/songsee/cmd/songsee@latest-```--可选:安装 `ffmpeg` 以支持 WAV/MP3 以外的格式。--## 快速开始--```bash-# 基本频谱图-songsee track.mp3--# 保存到指定文件-songsee track.mp3 -o spectrogram.png--# 多面板可视化网格-songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux--# 时间切片(从 12.5s 开始,持续 8s)-songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg--# 从 stdin 读取-cat track.mp3 | songsee - --format png -o out.png-```--## 可视化类型--使用 `--viz` 并以逗号分隔多个值:--| 类型 | 描述 |-|------|-------------|-| `spectrogram` | 标准频率频谱图 |-| `mel` | Mel 尺度频谱图 |-| `chroma` | 音高类别分布 |-| `hpss` | 谐波/打击乐分离 |-| `selfsim` | 自相似矩阵 |-| `loudness` | 随时间变化的响度 |-| `tempogram` | 节拍估计 |-| `mfcc` | Mel 频率倒谱系数 |-| `flux` | 频谱通量(起始点检测) |--多个 `--viz` 类型将以网格形式渲染为单张图像。--## 常用标志--| 标志 | 描述 |-|------|-------------|-| `--viz` | 可视化类型(逗号分隔) |-| `--style` | 色彩调色板:`classic`、`magma`、`inferno`、`viridis`、`gray` |-| `--width` / `--height` | 输出图像尺寸 |-| `--window` / `--hop` | FFT 窗口和跳跃大小 |-| `--min-freq` / `--max-freq` | 频率范围过滤 |-| `--start` / `--duration` | 音频时间切片 |-| `--format` | 输出格式:`jpg` 或 `png` |-| `-o` | 输出文件路径 |--## 注意事项--- WAV 和 MP3 原生解码;其他格式需要 `ffmpeg`-- 输出图像可使用 `vision_analyze` 进行检查,以实现自动化音频分析-- 适用于比较音频输出、调试合成过程或记录音频处理流水线\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-airtable.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-airtable.mddeleted file mode 100644index 824542b80fb..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-airtable.md+++ /dev/null@@ -1,243 +0,0 @@-----title: "Airtable — 通过 curl 调用 Airtable REST API"-sidebar_label: "Airtable"-description: "通过 curl 调用 Airtable REST API"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Airtable--通过 curl 调用 Airtable REST API。支持记录的增删改查、过滤和 upsert 操作。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/productivity/airtable` |-| 版本 | `1.1.0` |-| 作者 | community |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `Airtable`, `Productivity`, `Database`, `API` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# Airtable — Bases、Tables 与 Records--通过 `terminal` 工具,使用 `curl` 直接调用 Airtable 的 REST API。无需 MCP server,无需 OAuth 流程,无需 Python SDK——只需 `curl` 和一个个人访问令牌(PAT)。--## 前置条件--1. 在 https://airtable.com/create/tokens 创建一个**个人访问令牌(PAT)**(令牌以 `pat...` 开头)。-2. 授予以下权限范围(最低要求):- - `data.records:read` — 读取行- - `data.records:write` — 创建 / 更新 / 删除行- - `schema.bases:read` — 列出 bases 和 tables-3. **重要:** 在同一令牌 UI 中,将你需要访问的每个 base 添加到令牌的 **Access** 列表中。PAT 是按 base 划定范围的——有效令牌若未授权对应 base 会返回 `403`。-4. 将令牌存储在 `~/.hermes/.env` 中(或通过 `hermes setup` 配置):- ```- AIRTABLE_API_KEY=pat_your_token_here- ```--> 注意:旧版 `key...` API 密钥已于 2024 年 2 月弃用。目前仅支持 PAT 和 OAuth 令牌。--## API 基础--- **端点:** `https://api.airtable.com/v0`-- **认证头:** `Authorization: Bearer $AIRTABLE_API_KEY`-- **所有请求** 使用 JSON(POST/PATCH/PUT 请求体需设置 `Content-Type: application/json`)。-- **对象 ID:** base 为 `app...`,table 为 `tbl...`,record 为 `rec...`,field 为 `fld...`。ID 永不变更;名称可能变更。自动化流程中优先使用 ID。-- **速率限制:** 每个 base 每秒 5 次请求。收到 `429` 时需退避重试。单个 base 的突发请求会被限流。--基础 curl 模式:-```bash-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--`-s` 会抑制 curl 的进度条——每次调用都保持此设置,以确保工具输出对 Hermes 保持整洁。通过 `python3 -m json.tool`(始终可用)或 `jq`(若已安装)管道输出以获得可读的 JSON。--## 字段类型(请求体格式)--| 字段类型 | 写入格式 |-|---|---|-| 单行文本 | `"Name": "hello"` |-| 长文本 | `"Notes": "multi\nline"` |-| 数字 | `"Score": 42` |-| 复选框 | `"Done": true` |-| 单选 | `"Status": "Todo"`(选项名必须已存在,除非设置 `typecast: true`) |-| 多选 | `"Tags": ["urgent", "bug"]` |-| 日期 | `"Due": "2026-04-01"` |-| 日期时间(UTC) | `"At": "2026-04-01T14:30:00.000Z"` |-| URL / 邮箱 / 电话 | `"Link": "https://…"` |-| 附件 | `"Files": [{"url": "https://…"}]`(Airtable 会抓取并重新托管) |-| 关联记录 | `"Owner": ["recXXXXXXXXXXXXXX"]`(record ID 数组) |-| 用户 | `"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}` |--在创建/更新请求体的顶层传入 `"typecast": true`,可让 Airtable 自动强制转换值(例如动态创建新的单选选项,或将 `"42"` 转换为 `42`)。--## 常用查询--### 列出令牌可访问的 bases-```bash-curl -s "https://api.airtable.com/v0/meta/bases" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--### 列出某个 base 的 tables 及 schema-```bash-curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```-在执行任何变更操作前先调用此接口——可确认精确的字段名和 ID,查看单选字段的 `options.choices`,并获取主字段名称。--### 列出记录(前 10 条)-```bash-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--### 获取单条记录-```bash-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--### 过滤记录(filterByFormula)-Airtable 公式必须经过 URL 编码。使用 Python 标准库处理——切勿手动编码:-```bash-FORMULA="{Status}='Todo'"-ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--常用公式模式:-- 精确匹配:`{Email}='[email protected]'`-- 包含:`FIND('bug', LOWER({Title}))`-- 多条件:`AND({Status}='Todo', {Priority}='High')`-- 或:`OR({Owner}='alice', {Owner}='bob')`-- 非空:`NOT({Assignee}='')`-- 日期比较:`IS_AFTER({Due}, TODAY())`--### 排序并选择特定字段-```bash-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```-查询参数中的方括号必须进行 URL 编码(`%5B` / `%5D`)。--### 使用命名视图-```bash-curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```-视图会在服务端应用其保存的过滤条件和排序规则。--## 常用变更操作--### 创建单条记录-```bash-curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" \- -H "Content-Type: application/json" \- -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool-```--### 单次调用最多创建 10 条记录-```bash-curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "typecast": true,- "records": [- {"fields": {"Name": "Task A", "Status": "Todo"}},- {"fields": {"Name": "Task B", "Status": "In progress"}}- ]- }' | python3 -m json.tool-```-批量端点每次请求上限为 **10 条记录**。对于更大批量的插入,需以 10 条为一批循环处理,并在每批之间短暂休眠,以遵守每 base 每秒 5 次的速率限制。--### 更新记录(PATCH——合并更新,保留未修改字段)-```bash-curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" \- -H "Content-Type: application/json" \- -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool-```--### 按合并字段 upsert(无需 ID)-```bash-curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "performUpsert": {"fieldsToMergeOn": ["Email"]},- "records": [- {"fields": {"Email": "[email protected]", "Status": "Active"}}- ]- }' | python3 -m json.tool-```-`performUpsert` 会为合并字段值不存在的记录执行创建操作,为合并字段值已存在的记录执行更新操作。非常适合幂等同步场景。--### 删除单条记录-```bash-curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--### 单次调用最多删除 10 条记录-```bash-curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \- -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool-```--## 分页--列表端点每页最多返回 **100 条记录**。若响应中包含 `"offset": "..."`,需在下一次请求中传回该值。循环直至该字段不再出现:--```bash-OFFSET=""-while :; do- URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"- [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"- RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")- echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'- OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')- [ -z "$OFFSET" ] && break-done-```--## Hermes 典型工作流--1. **确认认证。** `curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY"` — 期望返回 `200`。-2. **找到 base。** 列出 bases(见上方步骤),或在令牌缺少 `schema.bases:read` 权限时直接向用户索取 `app...` ID。-3. **检查 schema。** `GET /v0/meta/bases/$BASE_ID/tables` — 在执行任何变更操作前,在会话中本地缓存精确的字段名和主字段名。-4. **写前先读。** 对于"更新满足条件 Y 的 X"类操作,先用 `filterByFormula` 解析出 `rec...` ID,再执行 `PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID`。切勿猜测 record ID。-5. **批量写入。** 将相关的创建操作合并为一次 10 条记录的 POST 请求,以控制在每秒 5 次的速率预算内。-6. **破坏性操作。** 删除操作无法通过 API 撤销。若用户要求"删除所有 X",先回显过滤条件和记录数量,确认后再执行。--## 注意事项--- **`filterByFormula` 必须进行 URL 编码。** 包含空格或非 ASCII 字符的字段名也需要编码(`{My Field}` → `%7BMy%20Field%7D`)。使用 Python 标准库(见上方模式)——切勿手动转义。-- **空字段不会出现在响应中。** 响应中缺少 `"Assignee"` 键并不意味着该字段不存在——而是表示该记录的值为空。在判断字段缺失之前,请先检查 schema(步骤 3)。-- **PATCH 与 PUT 的区别。** `PATCH` 将提供的字段合并到记录中。`PUT` 会完全替换记录,并清除所有未包含的字段。默认使用 `PATCH`。-- **单选选项必须已存在。** 若 `Shipping` 不在字段的选项列表中,写入 `"Status": "Shipping"` 会报错 `INVALID_MULTIPLE_CHOICE_OPTIONS`,除非传入 `"typecast": true`(会自动创建该选项)。-- **令牌的 base 范围限制。** 某个 base 返回 `403` 而其他 base 正常,说明该 base 未添加到令牌的 Access 列表中——而非权限范围或认证问题。请引导用户前往 https://airtable.com/create/tokens 授权。-- **速率限制是按 base 计算的,而非按令牌。** `baseA` 每秒 5 次、`baseB` 每秒 5 次是允许的;单独在 `baseA` 上每秒 6 次则会被限流。收到 `429` 时请监控 `Retry-After` 响应头。--## Hermes 重要说明--- **始终使用 `terminal` 工具配合 `curl`。** 不要使用 `web_extract`(无法发送认证头)或 `browser_exec`(需要 UI 认证且速度慢)。-- **`AIRTABLE_API_KEY` 会在此 skill 加载时自动从 `~/.hermes/.env` 注入到子进程环境中**——每次 `curl` 调用前无需重新导出。-- **在公式中谨慎转义花括号。** 在 heredoc 请求体中,`{Status}` 是字面量。在 shell 参数中,`{Status}` 在 `{...}` 大括号展开上下文之外是安全的——但在拼接到 URL 之前,动态字符串应通过 `python3 urllib.parse.quote` 处理。-- **使用 `python3 -m json.tool` 格式化输出**(始终可用),而非 `jq`(可选)。仅在需要过滤/投影时才使用 `jq`。-- **分页是按页计算的,而非全局。** Airtable 的 100 条记录上限是硬性限制,无法调整。使用 `offset` 循环直至该字段不再出现。-- **读取非 2xx 响应中的 `errors` 数组**——Airtable 会返回结构化错误码,如 `AUTHENTICATION_REQUIRED`、`INVALID_PERMISSIONS`、`MODEL_ID_NOT_FOUND`、`INVALID_MULTIPLE_CHOICE_OPTIONS`,可精确定位问题所在。\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-notion.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-notion.mddeleted file mode 100644index 114a03955f6..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-notion.md+++ /dev/null@@ -1,463 +0,0 @@-----title: "Notion — Notion API + ntn CLI:页面、数据库、Markdown、Workers"-sidebar_label: "Notion"-description: "Notion API + ntn CLI:页面、数据库、Markdown、Workers"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Notion--Notion API + ntn CLI:页面、数据库、Markdown、Workers。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/productivity/notion` |-| 版本 | `2.0.0` |-| 作者 | community |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `Notion`, `Productivity`, `Notes`, `Database`, `API`, `CLI`, `Workers` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# Notion--通过两种方式与 Notion 交互。两种方式使用同一个集成 token——根据可用情况选择。--◆ **`ntn` CLI** — Notion 官方 CLI。语法更简洁,支持单行文件上传,Workers 必须使用此方式。截至 2026 年 5 月仅支持 macOS + Linux(Windows 支持"即将推出")。**已安装时为默认方式。**-◆ **HTTP + curl** — 全平台可用,包括 Windows。**`ntn` 未安装时的默认回退方式。**--## 配置--### 1. 获取集成 token(两种方式均需要)--1. 在 https://notion.so/my-integrations 创建集成-2. 复制 API 密钥(以 `ntn_` 或 `secret_` 开头)-3. 存储到 `~/.hermes/.env`:- ```- NOTION_API_KEY=ntn_your_key_here- ```-4. **在 Notion 中将目标页面/数据库共享给该集成:** 页面菜单 `...` → `Connect to` → 你的集成名称。若未执行此步骤,即使页面存在,API 也会返回 404。--### 2. 安装 `ntn`(macOS / Linux 上的首选方式)--```bash-# 推荐方式-curl -fsSL https://ntn.dev | bash--# 或通过 npm 安装(需要 Node 22+,npm 10+)-npm install --global ntn--ntn --version # 验证安装-```--**跳过 `ntn login`——改用集成 token。** 此方式支持无头运行,无需浏览器:-```bash-export NOTION_API_TOKEN=$NOTION_API_KEY # ntn 读取 NOTION_API_TOKEN-export NOTION_KEYRING=0 # 不尝试使用系统密钥链-```--将上述 export 添加到你的 shell 配置文件(或 `~/.hermes/.env`),使每个会话都能继承这些变量。--### 3. 运行时选择路径--```bash-if command -v ntn >/dev/null 2>&1; then- # 使用 ntn-else- # 回退到 curl-fi-```--Windows 用户:在原生 `ntn` 发布之前完全跳过第 2 步——Path B 可正常使用。如果现在就想要 CLI 体验,可在 WSL2 中安装 `ntn`。--## API 基础--所有 HTTP 请求均需携带 `Notion-Version: 2025-09-03`。`ntn` 会自动处理此项。在此版本中,用户所称的"数据库"在 API 中称为 **data sources(数据源)**。--## Path A — `ntn` CLI(首选,macOS / Linux)--### 原始 API 调用(curl 的简写)-```bash-ntn api v1/users # GET-ntn api v1/pages parent[page_id]=abc123 \ # POST,内联请求体- properties[title][0][text][content]="Notes"-ntn api v1/pages/abc123 -X PATCH archived:=true # PATCH;:= 表示非字符串类型(布尔/数字/null)-```--语法说明:-- `key=value` — 字符串字段-- `key[nested]=value` — 嵌套对象字段-- `key:=value` — 类型赋值(布尔值、数字、null、数组)--### 搜索-```bash-ntn api v1/search query="page title"-```--### 读取页面元数据-```bash-ntn api v1/pages/{page_id}-```--### 以 Markdown 格式读取页面(适合 agent 使用)-```bash-ntn api v1/pages/{page_id}/markdown-```--### 以块(block)形式读取页面内容-```bash-ntn api v1/blocks/{page_id}/children-```--### 从 Markdown 创建页面-```bash-ntn api v1/pages \- parent[page_id]=xxx \- properties[title][0][text][content]="Notes from meeting" \- markdown="# Agenda--- Q3 roadmap-- Hiring"-```--### 用 Markdown 更新页面-```bash-ntn api v1/pages/{page_id}/markdown -X PATCH \- markdown="## Update--Shipped the prototype."-```--### 查询数据库(data source)-```bash-ntn api v1/data_sources/{data_source_id}/query -X POST \- filter[property]=Status filter[select][equals]=Active-```--对于包含 `sorts`、多个过滤条件或复合逻辑的复杂查询,通过管道传入 JSON:-```bash-echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \- ntn api v1/data_sources/{data_source_id}/query -X POST --json --```--### 文件上传(单行命令——CLI 最大优势)-```bash-ntn files create < photo.png-ntn files create --external-url https://example.com/photo.png-ntn files list-```--对比三步 HTTP 流程(创建上传 → PUT 字节 → 引用)。--### 常用环境变量-| 变量 | 作用 |-|---|---|-| `NOTION_API_TOKEN` | 认证 token(覆盖密钥链)——设置为你的集成 token |-| `NOTION_KEYRING=0` | 使用 `~/.config/notion/auth.json` 存储凭据,而非系统密钥链 |-| `NOTION_WORKSPACE_ID` | 跳过工作区选择提示 |--## Path B — HTTP + curl(跨平台,Windows 默认方式)--所有请求遵循以下模式:--```bash-curl -s -X GET "https://api.notion.com/v1/..." \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json"-```--Windows 10+ 自带的 `curl` 可直接使用。PowerShell 用户也可使用 `Invoke-RestMethod`。--### 搜索-```bash-curl -s -X POST "https://api.notion.com/v1/search" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{"query": "page title"}'-```--### 读取页面元数据-```bash-curl -s "https://api.notion.com/v1/pages/{page_id}" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03"-```--### 以 Markdown 格式读取页面(适合 agent 使用)--比块 JSON 更易于输入模型处理。--```bash-curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03"-```--### 以块形式读取页面内容(需要结构化数据时使用)-```bash-curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03"-```--### 从 Markdown 创建页面--`POST /v1/pages` 接受 `markdown` 请求体参数。--```bash-curl -s -X POST "https://api.notion.com/v1/pages" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{- "parent": {"page_id": "xxx"},- "properties": {"title": [{"text": {"content": "Notes from meeting"}}]},- "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday"- }'-```--### 用 Markdown 更新页面-```bash-curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{"markdown": "## Update\n\nShipped the prototype."}'-```--### 在数据库中创建页面(带类型属性)-```bash-curl -s -X POST "https://api.notion.com/v1/pages" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{- "parent": {"database_id": "xxx"},- "properties": {- "Name": {"title": [{"text": {"content": "New Item"}}]},- "Status": {"select": {"name": "Todo"}}- }- }'-```--### 查询数据库(data source)-```bash-curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{- "filter": {"property": "Status", "select": {"equals": "Active"}},- "sorts": [{"property": "Date", "direction": "descending"}]- }'-```--### 创建数据库-```bash-curl -s -X POST "https://api.notion.com/v1/data_sources" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{- "parent": {"page_id": "xxx"},- "title": [{"text": {"content": "My Database"}}],- "properties": {- "Name": {"title": {}},- "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},- "Date": {"date": {}}- }- }'-```--### 更新页面属性-```bash-curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'-```--### 向页面追加块-```bash-curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{- "children": [- {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello from Hermes!"}}]}}- ]- }'-```--### 文件上传(三步流程)-```bash-# 1. 创建上传-curl -s -X POST "https://api.notion.com/v1/file_uploads" \- -H "Authorization: Bearer $NOTION_API_KEY" \- -H "Notion-Version: 2025-09-03" \- -H "Content-Type: application/json" \- -d '{"filename": "photo.png", "content_type": "image/png"}'--# 2. 将字节 PUT 到上面返回的 upload_url-curl -s -X PUT "{upload_url}" --data-binary @photo.png--# 3. 在页面/块 payload 中引用 {file_upload_id}-```--## 属性类型--数据库条目的常用属性格式:--- **标题(Title):** `{"title": [{"text": {"content": "..."}}]}`-- **富文本(Rich text):** `{"rich_text": [{"text": {"content": "..."}}]}`-- **单选(Select):** `{"select": {"name": "Option"}}`-- **多选(Multi-select):** `{"multi_select": [{"name": "A"}, {"name": "B"}]}`-- **日期(Date):** `{"date": {"start": "2026-01-15", "end": "2026-01-16"}}`-- **复选框(Checkbox):** `{"checkbox": true}`-- **数字(Number):** `{"number": 42}`-- **URL:** `{"url": "https://..."}`-- **邮箱(Email):** `{"email": "[email protected]"}`-- **关联(Relation):** `{"relation": [{"id": "page_id"}]}`--## API 版本 2025-09-03 — 数据库与 Data Sources--- **数据库已更名为 data sources。** 查询和检索请使用 `/data_sources/` 端点。-- **每个数据库有两个 ID:** `database_id` 和 `data_source_id`。- - 创建页面时使用 `database_id`:`parent: {"database_id": "..."}`- - 查询时使用 `data_source_id`:`POST /v1/data_sources/{id}/query`-- 搜索返回的数据库对象类型为 `"object": "data_source"`,包含 `data_source_id` 字段。--## Notion Workers(高级功能,需要 `ntn`)--Workers 是由 Notion 托管的 TypeScript 程序。一个 worker 可以暴露以下任意组合:-- **Syncs(同步)** — 按计划(默认 30 分钟)从外部 API 拉取数据到 Notion 数据库。-- **Tools(工具)** — 在 Notion 的 Custom Agents 中作为可调用工具出现。-- **Webhooks** — 接收来自外部服务(GitHub、Stripe 等)的 HTTP 事件并在 Notion 中执行操作。--**套餐/平台限制:**-- CLI 在所有套餐上均可使用。**部署 Workers 需要 Business 或 Enterprise 套餐。**-- 截至 2026 年 5 月,`ntn` 仅支持 macOS/Linux。Windows 用户需使用 WSL2 或等待原生支持。-- 2026 年 8 月 11 日前免费;之后按 Notion 积分计费。--### 最简 Worker--```bash-ntn workers new my-worker # 脚手架-cd my-worker-# 编辑 src/index.ts-ntn workers deploy --name my-worker-```--`src/index.ts`:-```typescript-import { Worker } from "@notionhq/workers";--const worker = new Worker();-export default worker;--worker.tool("greet", {- title: "Greet a User",- description: "Returns a friendly greeting",- inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },- execute: async ({ name }) => `Hello, ${name}!`,-});-```--### Webhook 能力--```typescript-worker.webhook("onGithubPush", {- title: "GitHub Push Handler",- execute: async (events, { notion }) => {- for (const event of events) {- // event.body, event.rawBody(用于签名验证),event.headers- console.log("got delivery", event.deliveryId);- }- },-});-```--部署后:`ntn workers webhooks list` 显示 Notion 生成的 URL。将该 URL 视为机密——除非添加签名验证,否则任何人都可以向其 POST 事件。--### Worker 生命周期命令--```bash-ntn workers deploy-ntn workers list-ntn workers exec <capability-key> -d '{"name": "world"}'-ntn workers sync trigger <key> # 立即运行同步-ntn workers sync pause <key>-ntn workers env set GITHUB_WEBHOOK_SECRET=...-ntn workers runs list # 最近的调用记录-ntn workers runs logs <run-id>-ntn workers webhooks list-```--需要构建 Worker 时,使用 `ntn workers new` 创建脚手架,在 `src/index.ts` 中编写代码,通过 `ntn workers env set` 设置密钥,然后部署。Notion 文档 https://developers.notion.com/workers 涵盖完整 API 接口。--## Notion 风格 Markdown(用于 `/markdown` 端点)--标准 CommonMark 加上用于 Notion 特定块的类 XML 标签。缩进使用**制表符(tab)**。--**CommonMark 之外的块:**-```-<callout icon="🎯" color="blue_bg">- Ship the MVP by **Friday**.-</callout>--<details color="gray">-<summary>Toggle title</summary>- Children indented one tab-</details>--<columns>- <column>Left side</column>- <column>Right side</column>-</columns>--<table_of_contents color="gray"/>-```--**内联:**-- 提及(Mention):`<mention-user url="..."/>`、`<mention-page url="...">Title</mention-page>`、`<mention-date start="2026-05-15"/>`-- 下划线:`<span underline="true">text</span>`-- 颜色:`<span color="blue">text</span>`,或块级别在第一行使用 `{color="blue"}`-- 数学公式:内联 `$x^2$`,块级 `$$ ... $$`-- 引用:`[^https://example.com]`--**颜色:** `gray brown orange yellow green blue purple pink red`,以及带 `*_bg` 后缀的背景色变体。--5/6 级标题会折叠为 H4。多个连续 `>` 行渲染为独立引用块——在单个 `>` 内使用 `<br>` 实现多行引用。--## 选择合适的路径--| 任务 | macOS / Linux | Windows |-|---|---|---|-| 读写页面、搜索、查询数据库 | `ntn api ...` | curl |-| 读取页面供 agent 摘要 | `ntn api v1/pages/{id}/markdown` | curl `/markdown` 端点 |-| 上传文件 | `ntn files create < file` | 三步 HTTP 流程 |-| 一次性 API 探索 | `ntn api ...` | curl |-| 构建由 Notion 托管的同步/webhook/agent 工具 | `ntn workers ...` | WSL2 + `ntn workers ...` |--## 注意事项--- 页面/数据库 ID 为 UUID 格式(带或不带连字符均可接受)。-- 速率限制:平均约 3 次请求/秒。CLI 不会绕过此限制。-- API 无法设置数据库**视图**过滤器——该功能仅限 UI 操作。-- 创建 data sources 时使用 `"is_inline": true` 可将其嵌入页面。-- 始终为 curl 传入 `-s` 以抑制进度条(使 agent 输出更整洁)。-- 读取数据时通过 `jq` 管道处理:`... | jq '.results[0].properties'`。-- Notion 现已推出 MCP 服务器(`Notion MCP`,在数据库操作上比上一版本的 token 效率提升约 91%)——如需在会话中进行流式 Notion 访问,可通过 Hermes 的 MCP 支持接入,但上述路径已足以应对大多数一次性任务。\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-powerpoint.mddeleted file mode 100644index 226844602c0..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/productivity/productivity-powerpoint.md+++ /dev/null@@ -1,257 +0,0 @@-----title: "Powerpoint — 创建、读取、编辑"-sidebar_label: "Powerpoint"-description: "创建、读取、编辑"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Powerpoint--创建、读取、编辑 .pptx 幻灯片、备注、模板。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/productivity/powerpoint` |-| 许可证 | 专有。完整条款见 LICENSE.txt |-| 平台 | linux, macos, windows |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# Powerpoint Skill--## 使用时机--只要涉及 .pptx 文件——无论作为输入、输出还是两者兼有——均使用此 skill。包括:创建幻灯片、演示文稿或 pitch deck;读取、解析或提取任意 .pptx 文件中的文本(即使提取的内容将用于其他地方,如邮件或摘要);编辑、修改或更新现有演示文稿;合并或拆分幻灯片文件;处理模板、布局、演讲者备注或注释。只要用户提到"deck"、"slides"、"presentation"或引用了 .pptx 文件名,无论之后计划如何使用内容,均触发此 skill。如果需要打开、创建或操作 .pptx 文件,请使用此 skill。--## 快速参考--| 任务 | 指南 |-|------|-------|-| 读取/分析内容 | `python -m markitdown presentation.pptx` |-| 基于模板编辑或创建 | 阅读 [editing.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/editing.md) |-| 从零创建 | 阅读 [pptxgenjs.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/pptxgenjs.md) |-------## 读取内容--```bash-# 文本提取-python -m markitdown presentation.pptx--# 可视化概览-python scripts/thumbnail.py presentation.pptx--# 原始 XML-python scripts/office/unpack.py presentation.pptx unpacked/-```-------## 编辑工作流--**完整细节请阅读 [editing.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/editing.md)。**--1. 使用 `thumbnail.py` 分析模板-2. 解包 → 操作幻灯片 → 编辑内容 → 清理 → 打包-------## 从零创建--**完整细节请阅读 [pptxgenjs.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/pptxgenjs.md)。**--在没有模板或参考演示文稿时使用。-------## 设计建议--**不要创建无聊的幻灯片。** 白底纯文字列表不会给任何人留下深刻印象。请针对每张幻灯片参考以下建议。--### 开始之前--- **选择大胆、契合内容的配色方案**:配色应专为该主题而设计。如果把你的配色套用到完全不同的演示文稿中仍然"可用",说明选择还不够具体。-- **主次分明,而非平均分配**:一种颜色应占主导地位(60-70% 视觉比重),搭配 1-2 种辅助色和一种鲜明的强调色。切勿让所有颜色平分秋色。-- **深浅对比**:标题页和结尾页用深色背景,内容页用浅色("三明治"结构)。或全程使用深色背景以营造高端感。-- **坚持一种视觉母题**:选择一种独特元素并贯穿始终——圆角图片框、彩色圆圈内的图标、单侧粗边框。在每张幻灯片上保持一致。--### 配色方案--根据主题选择配色,不要默认使用通用蓝色。以下配色方案仅供参考:--| 主题 | 主色 | 辅助色 | 强调色 |-|-------|---------|-----------|--------|-| **午夜商务** | `1E2761`(深海蓝) | `CADCFC`(冰蓝) | `FFFFFF`(白) |-| **森林苔藓** | `2C5F2D`(森林绿) | `97BC62`(苔绿) | `F5F5F5`(米白) |-| **珊瑚活力** | `F96167`(珊瑚红) | `F9E795`(金黄) | `2F3C7E`(深蓝) |-| **暖陶土** | `B85042`(陶土红) | `E7E8D1`(沙色) | `A7BEAE`(鼠尾草绿) |-| **海洋渐变** | `065A82`(深蓝) | `1C7293`(青蓝) | `21295C`(午夜蓝) |-| **炭灰极简** | `36454F`(炭灰) | `F2F2F2`(近白) | `212121`(黑) |-| **青蓝信任** | `028090`(青蓝) | `00A896`(海泡绿) | `02C39A`(薄荷绿) |-| **浆果奶油** | `6D2E46`(浆果紫) | `A26769`(玫瑰灰) | `ECE2D0`(奶油) |-| **鼠尾草静谧** | `84B59F`(鼠尾草绿) | `69A297`(桉叶绿) | `50808E`(石板蓝) |-| **樱桃醒目** | `990011`(樱桃红) | `FCF6F5`(近白) | `2F3C7E`(深蓝) |--### 每张幻灯片--**每张幻灯片都需要视觉元素**——图片、图表、图标或形状。纯文字幻灯片令人印象全无。--**布局选项:**-- 双栏(左文字,右插图)-- 图标 + 文字行(彩色圆圈内图标,粗体标题,下方描述)-- 2x2 或 2x3 网格(一侧图片,另一侧内容块网格)-- 半出血图片(左侧或右侧全满)配内容叠加--**数据展示:**-- 大数字标注(60-72pt 大号数字,下方小标签)-- 对比列(前后对比、优缺点、并排选项)-- 时间线或流程图(编号步骤、箭头)--**视觉精修:**-- 章节标题旁的小彩色圆圈内放图标-- 关键数据或标语使用斜体强调文字--### 字体排版--**选择有趣的字体搭配**——不要默认使用 Arial。选择一种有个性的标题字体,搭配简洁的正文字体。--| 标题字体 | 正文字体 |-|-------------|-----------|-| Georgia | Calibri |-| Arial Black | Arial |-| Calibri | Calibri Light |-| Cambria | Calibri |-| Trebuchet MS | Calibri |-| Impact | Arial |-| Palatino | Garamond |-| Consolas | Calibri |--| 元素 | 字号 |-|---------|------|-| 幻灯片标题 | 36-44pt 粗体 |-| 章节标题 | 20-24pt 粗体 |-| 正文 | 14-16pt |-| 说明文字 | 10-12pt 弱化色 |--### 间距--- 最小 0.5" 边距-- 内容块之间 0.3-0.5"-- 留有呼吸空间——不要填满每一寸--### 避免(常见错误)--- **不要重复相同布局**——在幻灯片间变换列、卡片和标注-- **不要居中对齐正文**——段落和列表左对齐;仅标题居中-- **不要忽视字号对比**——标题需 36pt 以上才能从 14-16pt 正文中突出-- **不要默认使用蓝色**——选择能反映具体主题的颜色-- **不要随意混用间距**——选定 0.3" 或 0.5" 的间隔后保持一致-- **不要只精心设计一张幻灯片而其余保持简陋**——要么全力投入,要么全程保持简洁-- **不要创建纯文字幻灯片**——添加图片、图标、图表或视觉元素;避免纯标题 + 列表-- **不要忘记文本框内边距**——将线条或形状与文字边缘对齐时,将文本框的 `margin` 设为 `0`,或偏移形状以补偿内边距-- **不要使用低对比度元素**——图标和文字都需要与背景形成强烈对比;避免浅色背景上的浅色文字或深色背景上的深色文字-- **绝对不要在标题下方使用装饰线**——这是 AI 生成幻灯片的典型特征;改用留白或背景色-------## QA(必须执行)--**假设存在问题。你的任务是找出它们。**--第一次渲染几乎从不正确。将 QA 视为查找 bug,而非确认步骤。如果第一次检查没有发现任何问题,说明你看得还不够仔细。--### 内容 QA--```bash-python -m markitdown output.pptx-```--检查缺失内容、错别字、顺序错误。--**使用模板时,检查是否残留占位符文本:**--```bash-python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"-```--如果 grep 返回结果,在宣告完成前先修复。--### 视觉 QA--**⚠️ 使用子 agent**——即使只有 2-3 张幻灯片。你一直盯着代码,会看到你期望看到的,而非实际存在的。子 agent 有全新的视角。--将幻灯片转换为图片(见[转换为图片](#converting-to-images)),然后使用以下 prompt(提示词):--```-Visually inspect these slides. Assume there are issues — find them.--Look for:-- Overlapping elements (text through shapes, lines through words, stacked elements)-- Text overflow or cut off at edges/box boundaries-- Decorative lines positioned for single-line text but title wrapped to two lines-- Source citations or footers colliding with content above-- Elements too close (< 0.3" gaps) or cards/sections nearly touching-- Uneven gaps (large empty area in one place, cramped in another)-- Insufficient margin from slide edges (< 0.5")-- Columns or similar elements not aligned consistently-- Low-contrast text (e.g., light gray text on cream-colored background)-- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)-- Text boxes too narrow causing excessive wrapping-- Leftover placeholder content--For each slide, list issues or areas of concern, even if minor.--Read and analyze these images:-1. /path/to/slide-01.jpg (Expected: [brief description])-2. /path/to/slide-02.jpg (Expected: [brief description])--Report ALL issues found, including minor ones.-```--### 验证循环--1. 生成幻灯片 → 转换为图片 → 检查-2. **列出发现的问题**(如果未发现任何问题,请更严格地再看一遍)-3. 修复问题-4. **重新验证受影响的幻灯片**——一处修复往往会引发另一个问题-5. 重复,直到完整检查一遍后不再出现新问题--**在完成至少一次修复并验证的循环之前,不得宣告成功。**-------## 转换为图片--将演示文稿转换为单张幻灯片图片以供视觉检查:--```bash-python scripts/office/soffice.py --headless --convert-to pdf output.pptx-pdftoppm -jpeg -r 150 output.pdf slide-```--这将生成 `slide-01.jpg`、`slide-02.jpg` 等文件。--修复后重新渲染特定幻灯片:--```bash-pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed-```-------## 依赖项--- `pip install "markitdown[pptx]"` - 文本提取-- `pip install Pillow` - 缩略图网格-- `npm install -g pptxgenjs` - 从零创建-- LibreOffice(`soffice`)- PDF 转换(通过 `scripts/office/soffice.py` 为沙箱环境自动配置)-- Poppler(`pdftoppm`)- PDF 转图片\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-llm-wiki.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-llm-wiki.mddeleted file mode 100644index 232f44fbb05..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-llm-wiki.md+++ /dev/null@@ -1,469 +0,0 @@-----title: "Llm Wiki — Karpathy 的 LLM Wiki:构建/查询互联 Markdown 知识库"-sidebar_label: "Llm Wiki"-description: "Karpathy 的 LLM Wiki:构建/查询互联 Markdown 知识库"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Llm Wiki--Karpathy 的 LLM Wiki:构建/查询互联 Markdown 知识库。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/research/llm-wiki` |-| 版本 | `2.1.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `wiki`, `knowledge-base`, `research`, `notes`, `markdown`, `rag-alternative` |-| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 看到的指令内容。-:::--# Karpathy 的 LLM Wiki--将知识库构建并维护为互联 Markdown 文件,持续积累、复利增长。-基于 [Andrej Karpathy 的 LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。--与传统 RAG(每次查询都从头重新发现知识)不同,wiki 只编译一次知识并保持更新。交叉引用已就位,矛盾已被标记,综合分析反映了所有已摄入的内容。--**分工:** 人类负责筛选来源并指导分析。Agent 负责摘要、交叉引用、归档和维护一致性。--## 此 Skill 的激活时机--当用户执行以下操作时使用此 skill:-- 要求创建、构建或启动 wiki 或知识库-- 要求将某个来源摄入(ingest)、添加或处理到 wiki 中-- 提出问题,且配置路径下已存在 wiki-- 要求对 wiki 进行 lint、审计或健康检查-- 在研究场景中提及其 wiki、知识库或"笔记"--## Wiki 位置--**位置:** 通过 `WIKI_PATH` 环境变量设置(例如在 `~/.hermes/.env` 中)。--未设置时,默认为 `~/wiki`。--```bash-WIKI="${WIKI_PATH:-$HOME/wiki}"-```--Wiki 只是一个 Markdown 文件目录——可在 Obsidian、VS Code 或任意编辑器中打开。无需数据库,无需特殊工具。--## 架构:三层结构--<!-- ascii-guard-ignore -->-```-wiki/-├── SCHEMA.md # Conventions, structure rules, domain config-├── index.md # Sectioned content catalog with one-line summaries-├── log.md # Chronological action log (append-only, rotated yearly)-├── raw/ # Layer 1: Immutable source material-│ ├── articles/ # Web articles, clippings-│ ├── papers/ # PDFs, arxiv papers-│ ├── transcripts/ # Meeting notes, interviews-│ └── assets/ # Images, diagrams referenced by sources-├── entities/ # Layer 2: Entity pages (people, orgs, products, models)-├── concepts/ # Layer 2: Concept/topic pages-├── comparisons/ # Layer 2: Side-by-side analyses-└── queries/ # Layer 2: Filed query results worth keeping-```-<!-- ascii-guard-ignore-end -->--**第一层——原始来源:** 不可变。Agent 只读,不修改。-**第二层——Wiki 正文:** Agent 拥有的 Markdown 文件,由 Agent 创建、更新和交叉引用。-**第三层——Schema:** `SCHEMA.md` 定义结构、约定和标签分类体系。--## 恢复已有 Wiki(关键——每次会话都必须执行)--当用户已有 wiki 时,**在执行任何操作前务必先定位自身**:--① **读取 `SCHEMA.md`** — 了解领域、约定和标签分类体系。-② **读取 `index.md`** — 了解已有页面及其摘要。-③ **扫描近期 `log.md`** — 读取最后 20-30 条记录,了解近期活动。--```bash-WIKI="${WIKI_PATH:-$HOME/wiki}"-# Orientation reads at session start-read_file "$WIKI/SCHEMA.md"-read_file "$WIKI/index.md"-read_file "$WIKI/log.md" offset=<last 30 lines>-```--只有完成定位后,才可进行摄入、查询或 lint 操作。这可以防止:-- 为已存在的实体创建重复页面-- 遗漏对已有内容的交叉引用-- 违反 schema 约定-- 重复已记录的工作--对于大型 wiki(100+ 页),在创建任何新内容前,还需针对当前主题快速执行 `search_files`。--## 初始化新 Wiki--当用户要求创建或启动 wiki 时:--1. 确定 wiki 路径(从 `$WIKI_PATH` 环境变量获取,或询问用户;默认 `~/wiki`)-2. 创建上述目录结构-3. 询问用户 wiki 涵盖的领域——要具体-4. 编写针对该领域定制的 `SCHEMA.md`(见下方模板)-5. 编写带分节标题的初始 `index.md`-6. 编写包含创建条目的初始 `log.md`-7. 确认 wiki 已就绪,并建议首批摄入来源--### SCHEMA.md 模板--根据用户领域进行调整。Schema 约束 Agent 行为并确保一致性:--```markdown-# Wiki Schema--## Domain-[What this wiki covers — e.g., "AI/ML research", "personal health", "startup intelligence"]--## Conventions-- File names: lowercase, hyphens, no spaces (e.g., `transformer-architecture.md`)-- Every wiki page starts with YAML frontmatter (see below)-- Use `[[wikilinks]]` to link between pages (minimum 2 outbound links per page)-- When updating a page, always bump the `updated` date-- Every new page must be added to `index.md` under the correct section-- Every action must be appended to `log.md`-- **Provenance markers:** On pages that synthesize 3+ sources, append `^[raw/articles/source-file.md]`- at the end of paragraphs whose claims come from a specific source. This lets a reader trace each- claim back without re-reading the whole raw file. Optional on single-source pages where the- `sources:` frontmatter is enough.--## Frontmatter- ```yaml- ---- title: Page Title- created: YYYY-MM-DD- updated: YYYY-MM-DD- type: entity | concept | comparison | query | summary- tags: [from taxonomy below]- sources: [raw/articles/source-name.md]- # Optional quality signals:- confidence: high | medium | low # how well-supported the claims are- contested: true # set when the page has unresolved contradictions- contradictions: [other-page-slug] # pages this one conflicts with- ---- ```--`confidence` 和 `contested` 是可选字段,但对于观点性强或快速变化的主题建议填写。Lint 会将 `contested: true` 和 `confidence: low` 的页面标记出来供审查,防止薄弱论断悄然固化为公认的 wiki 事实。--### raw/ Frontmatter--原始来源**同样**需要一个小型 frontmatter 块,以便重新摄入时检测内容漂移:--```yaml-----source_url: https://example.com/article # original URL, if applicable-ingested: YYYY-MM-DD-sha256: <hex digest of the raw content below the frontmatter>-----```--`sha256:` 字段允许未来重新摄入同一 URL 时,在内容未变时跳过处理,在内容已变时标记漂移。仅对正文(frontmatter 结束 `---` 之后的所有内容)计算哈希,不含 frontmatter 本身。--## Tag Taxonomy-[Define 10-20 top-level tags for the domain. Add new tags here BEFORE using them.]--Example for AI/ML:-- Models: model, architecture, benchmark, training-- People/Orgs: person, company, lab, open-source-- Techniques: optimization, fine-tuning, inference, alignment, data-- Meta: comparison, timeline, controversy, prediction--Rule: every tag on a page must appear in this taxonomy. If a new tag is needed,-add it here first, then use it. This prevents tag sprawl.--## Page Thresholds-- **Create a page** when an entity/concept appears in 2+ sources OR is central to one source-- **Add to existing page** when a source mentions something already covered-- **DON'T create a page** for passing mentions, minor details, or things outside the domain-- **Split a page** when it exceeds ~200 lines — break into sub-topics with cross-links-- **Archive a page** when its content is fully superseded — move to `_archive/`, remove from index--## Entity Pages-One page per notable entity. Include:-- Overview / what it is-- Key facts and dates-- Relationships to other entities ([[wikilinks]])-- Source references--## Concept Pages-One page per concept or topic. Include:-- Definition / explanation-- Current state of knowledge-- Open questions or debates-- Related concepts ([[wikilinks]])--## Comparison Pages-Side-by-side analyses. Include:-- What is being compared and why-- Dimensions of comparison (table format preferred)-- Verdict or synthesis-- Sources--## Update Policy-When new information conflicts with existing content:-1. Check the dates — newer sources generally supersede older ones-2. If genuinely contradictory, note both positions with dates and sources-3. Mark the contradiction in frontmatter: `contradictions: [page-name]`-4. Flag for user review in the lint report-```--### index.md 模板--索引按类型分节。每条记录为一行:wikilink + 摘要。--```markdown-# Wiki Index--> Content catalog. Every wiki page listed under its type with a one-line summary.-> Read this first to find relevant pages for any query.-> Last updated: YYYY-MM-DD | Total pages: N--## Entities-<!-- Alphabetical within section -->--## Concepts--## Comparisons--## Queries-```--**扩展规则:** 当任意分节超过 50 条时,按首字母或子领域拆分为子节。当索引总条目超过 200 时,创建 `_meta/topic-map.md`,按主题对页面分组,以加快导航速度。--### log.md 模板--```markdown-# Wiki Log--> Chronological record of all wiki actions. Append-only.-> Format: `## [YYYY-MM-DD] action | subject`-> Actions: ingest, update, query, lint, create, archive, delete-> When this file exceeds 500 entries, rotate: rename to log-YYYY.md, start fresh.--## [YYYY-MM-DD] create | Wiki initialized-- Domain: [domain]-- Structure created with SCHEMA.md, index.md, log.md-```--## 核心操作--### 1. 摄入(Ingest)--当用户提供来源(URL、文件、粘贴内容)时,将其整合到 wiki 中:--① **捕获原始来源:**- - URL → 使用 `web_extract` 获取 Markdown,保存到 `raw/articles/`- - PDF → 使用 `web_extract`(支持 PDF),保存到 `raw/papers/`- - 粘贴文本 → 保存到对应的 `raw/` 子目录- - 文件名应具有描述性:`raw/articles/karpathy-llm-wiki-2026.md`- - **添加 raw frontmatter**(`source_url`、`ingested`、正文的 `sha256`)。- 重新摄入同一 URL 时:重新计算 sha256,与已存储值比较——相同则跳过,不同则标记漂移并更新。此操作成本极低,每次重新摄入都可执行,能捕获静默的来源变更。--② **与用户讨论要点** — 哪些内容有趣,哪些对领域重要。(自动化/cron 场景下跳过此步,直接继续。)--③ **检查已有内容** — 搜索 index.md,并使用 `search_files` 查找已提及实体/概念的现有页面。这是 wiki 持续增长与变成重复堆砌之间的关键区别。--④ **编写或更新 wiki 页面:**- - **新实体/概念:** 仅在满足 SCHEMA.md 中页面阈值时创建页面(2+ 来源提及,或在某一来源中处于核心地位)- - **已有页面:** 添加新信息,更新事实,更新 `updated` 日期。新信息与已有内容矛盾时,遵循更新策略。- - **交叉引用:** 每个新建或更新的页面必须通过 `[[wikilinks]]` 链接到至少 2 个其他页面。检查已有页面是否有反向链接。- - **标签:** 只使用 SCHEMA.md 分类体系中的标签- - **来源溯源:** 在综合 3+ 来源的页面上,在论断可追溯到特定来源的段落末尾添加 `^[raw/articles/source.md]` 标记。- - **置信度:** 对于观点性强、快速变化或单一来源的论断,在 frontmatter 中设置 `confidence: medium` 或 `low`。除非论断在多个来源中有充分支撑,否则不标记 `high`。--⑤ **更新导航:**- - 将新页面按字母顺序添加到 `index.md` 对应分节- - 更新 index 头部的"Total pages"计数和"Last updated"日期- - 追加到 `log.md`:`## [YYYY-MM-DD] ingest | Source Title`- - 在日志条目中列出每个创建或更新的文件--⑥ **报告变更内容** — 向用户列出每个创建或更新的文件。--单个来源可能触发 5-15 个 wiki 页面的更新。这是正常且期望的结果——这正是复利效应。--### 2. 查询(Query)--当用户就 wiki 领域提问时:--① **读取 `index.md`** 以识别相关页面。-② **对于 100+ 页的 wiki**,还需对所有 `.md` 文件执行 `search_files` 搜索关键词——仅靠索引可能遗漏相关内容。-③ **读取相关页面**,使用 `read_file`。-④ **从已编译的知识中综合答案**。引用所参考的 wiki 页面:"Based on [[page-a]] and [[page-b]]..."-⑤ **将有价值的答案归档** — 如果答案是实质性的比较、深度分析或新颖综合,在 `queries/` 或 `comparisons/` 中创建页面。不要归档琐碎的查询——只归档重新推导代价高昂的答案。-⑥ **更新 log.md**,记录查询内容及是否已归档。--### 3. Lint--当用户要求 lint、健康检查或审计 wiki 时:--① **孤立页面:** 查找没有其他页面通过 `[[wikilinks]]` 指向的页面。-```python-# Use execute_code for this — programmatic scan across all wiki pages-import os, re-from collections import defaultdict-wiki = "<WIKI_PATH>"-# Scan all .md files in entities/, concepts/, comparisons/, queries/-# Extract all [[wikilinks]] — build inbound link map-# Pages with zero inbound links are orphans-```--② **断开的 wikilink:** 查找指向不存在页面的 `[[links]]`。--③ **索引完整性:** 每个 wiki 页面都应出现在 `index.md` 中。对比文件系统与索引条目。--④ **Frontmatter 验证:** 每个 wiki 页面必须包含所有必填字段(title、created、updated、type、tags、sources)。标签必须在分类体系中。--⑤ **过时内容:** `updated` 日期比提及相同实体的最新来源早 90 天以上的页面。--⑥ **矛盾:** 涉及同一主题但论断相互冲突的页面。查找共享标签/实体但陈述不同事实的页面。将所有带有 `contested: true` 或 `contradictions:` frontmatter 的页面标记出来供用户审查。--⑦ **质量信号:** 列出 `confidence: low` 的页面,以及仅引用单一来源但未设置 confidence 字段的页面——这些页面是寻找佐证或降级为 `confidence: medium` 的候选。--⑧ **来源漂移:** 对 `raw/` 中每个带有 `sha256:` frontmatter 的文件,重新计算哈希并标记不匹配项。不匹配表明原始文件被编辑(不应发生——`raw/` 是不可变的)或从已变更的 URL 摄入。不是硬性错误,但值得报告。--⑨ **页面大小:** 标记超过 200 行的页面——拆分候选。--⑩ **标签审计:** 列出所有使用中的标签,标记不在 SCHEMA.md 分类体系中的标签。--⑪ **日志轮转:** 如果 log.md 超过 500 条,进行轮转。--⑫ **报告发现结果**,附具体文件路径和建议操作,按严重程度分组(断开链接 > 孤立页面 > 来源漂移 > 有争议页面 > 过时内容 > 样式问题)。--⑬ **追加到 log.md:** `## [YYYY-MM-DD] lint | N issues found`--## Wiki 使用方法--### 搜索--```bash-# Find pages by content-search_files "transformer" path="$WIKI" file_glob="*.md"--# Find pages by filename-search_files "*.md" target="files" path="$WIKI"--# Find pages by tag-search_files "tags:.*alignment" path="$WIKI" file_glob="*.md"--# Recent activity-read_file "$WIKI/log.md" offset=<last 20 lines>-```--### 批量摄入--同时摄入多个来源时,批量处理更新:-1. 先读取所有来源-2. 识别所有来源中的所有实体和概念-3. 一次性检查所有实体的已有页面(一次搜索,而非 N 次)-4. 一次性创建/更新页面(避免冗余更新)-5. 最后统一更新 index.md-6. 写一条涵盖整批操作的日志条目--### 归档--当内容完全被取代或领域范围发生变化时:-1. 如不存在则创建 `_archive/` 目录-2. 将页面移至 `_archive/`,保留原始路径(例如 `_archive/entities/old-page.md`)-3. 从 `index.md` 中移除-4. 更新所有链接到该页面的页面——将 wikilink 替换为纯文本 + "(已归档)"-5. 记录归档操作--### Obsidian 集成--Wiki 目录开箱即用作为 Obsidian vault:-- `[[wikilinks]]` 渲染为可点击链接-- 图谱视图可视化知识网络-- YAML frontmatter 支持 Dataview 查询-- `raw/assets/` 文件夹存放通过 `![[image.png]]` 引用的图片--最佳实践:-- 将 Obsidian 的附件文件夹设置为 `raw/assets/`-- 在 Obsidian 设置中启用"Wikilinks"(通常默认开启)-- 安装 Dataview 插件,支持如 `TABLE tags FROM "entities" WHERE contains(tags, "company")` 的查询--如果同时使用 Obsidian skill,将 `OBSIDIAN_VAULT_PATH` 设置为与 wiki 路径相同的目录。--### Obsidian 无头模式(服务器和无显示器机器)--在没有显示器的机器上,使用 `obsidian-headless` 代替桌面应用。它通过 Obsidian Sync 同步 vault,无需 GUI——非常适合在服务器上运行、向 wiki 写入内容,同时在另一台设备上用 Obsidian 桌面端读取的 Agent。--**设置:**-```bash-# Requires Node.js 22+-npm install -g obsidian-headless--# Login (requires Obsidian account with Sync subscription)-ob login --email <email> --password '<password>'--# Create a remote vault for the wiki-ob sync-create-remote --name "LLM Wiki"--# Connect the wiki directory to the vault-cd ~/wiki-ob sync-setup --vault "<vault-id>"--# Initial sync-ob sync--# Continuous sync (foreground — use systemd for background)-ob sync --continuous-```--**通过 systemd 实现持续后台同步:**-```ini-# ~/.config/systemd/user/obsidian-wiki-sync.service-[Unit]-Description=Obsidian LLM Wiki Sync-After=network-online.target-Wants=network-online.target--[Service]-ExecStart=/path/to/ob sync --continuous-WorkingDirectory=/home/user/wiki-Restart=on-failure-RestartSec=10--[Install]-WantedBy=default.target-```--```bash-systemctl --user daemon-reload-systemctl --user enable --now obsidian-wiki-sync-# Enable linger so sync survives logout:-sudo loginctl enable-linger $USER-```--这样 Agent 可以在服务器上向 `~/wiki` 写入内容,同时你在笔记本/手机上的 Obsidian 中浏览同一 vault——变更在数秒内即可同步。--## 注意事项--- **永远不要修改 `raw/` 中的文件** — 来源是不可变的。更正内容写入 wiki 页面。-- **始终先定位自身** — 在新会话中执行任何操作前,先读取 SCHEMA + index + 近期日志。跳过此步会导致重复和遗漏交叉引用。-- **始终更新 index.md 和 log.md** — 跳过此步会导致 wiki 退化。这两个文件是导航骨架。-- **不要为一笔带过的提及创建页面** — 遵循 SCHEMA.md 中的页面阈值。某个名称在脚注中出现一次,不足以创建实体页面。-- **不要创建没有交叉引用的页面** — 孤立页面是不可见的。每个页面必须链接到至少 2 个其他页面。-- **Frontmatter 是必填的** — 它支持搜索、过滤和过时检测。-- **标签必须来自分类体系** — 自由形式的标签会退化为噪音。先在 SCHEMA.md 中添加新标签,再使用。-- **保持页面可扫描** — wiki 页面应在 30 秒内可读完。超过 200 行的页面应拆分。将详细分析移至专用深度分析页面。-- **批量更新前先确认** — 如果一次摄入会影响 10+ 个已有页面,先与用户确认范围。-- **轮转日志** — 当 log.md 超过 500 条时,将其重命名为 `log-YYYY.md` 并重新开始。Agent 应在 lint 期间检查日志大小。-- **显式处理矛盾** — 不要静默覆盖。注明两种论断及其日期,在 frontmatter 中标记,标记供用户审查。--## 相关工具--[llm-wiki-compiler](https://github.com/atomicmemory/llm-wiki-compiler) 是一个 Node.js CLI,基于相同的 Karpathy 灵感将来源编译为概念 wiki。它兼容 Obsidian,因此希望使用定时/CLI 驱动编译流水线的用户可以将其指向此 skill 维护的同一 vault。权衡:它拥有页面生成的控制权(取代 Agent 在页面创建上的判断),并针对小型语料库进行了调优。当你希望 Agent 参与策划时使用此 skill;当你希望批量编译来源目录时使用 llmwiki。\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.mddeleted file mode 100644index f8e438730a8..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md+++ /dev/null@@ -1,184 +0,0 @@-----title: "Hermes Agent Skill 编写——在仓库中编写 SKILL"-sidebar_label: "Hermes Agent Skill 编写"-description: "在仓库中编写 SKILL.md"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Hermes Agent Skill 编写--编写仓库内 SKILL.md:frontmatter(前置元数据)、验证器、结构。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/software-development/hermes-agent-skill-authoring` |-| 版本 | `1.0.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` |-| 相关 skill | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# 编写 Hermes-Agent Skills(仓库内)--## 概述--SKILL.md 可以存放在两个位置:--1. **用户本地:** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — 个人使用,不共享。通过 `skill_manage(action='create')` 创建。-2. **仓库内(本 skill 讨论此情况):** `/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md` — 已提交,随包一起发布。使用 `write_file` + `git add`。`skill_manage(action='create')` **不**针对此目录树。--## 使用时机--- 用户要求你"在此分支 / 仓库 / 提交中"添加一个 skill-- 你正在提交一个应随 hermes-agent 一起发布的可复用工作流-- 你正在编辑 `/home/bb/hermes-agent/skills/` 下的现有 skill(小改动用 `patch`,重写用 `write_file`;`skill_manage` 对仓库内 skill 的 `patch` 仍有效,但 `create` 无效)--## 必需的 Frontmatter--真实来源:`tools/skill_manager_tool.py::_validate_frontmatter`。硬性要求:--- 以 `---` 作为首字节开头(无前导空行)。-- 在正文前以 `\n---\n` 结束。-- 可解析为 YAML 映射。-- 存在 `name` 字段。-- 存在 `description` 字段,且 ≤ **1024 个字符**(`MAX_DESCRIPTION_LENGTH`)。-- 关闭 `---` 后有非空正文。--`skills/software-development/` 下每个 skill 使用的对等匹配格式:--```yaml-----name: my-skill-name # 小写,连字符,≤64 个字符(MAX_NAME_LENGTH)-description: Use when <trigger>. <one-line behavior>.-version: 1.0.0-author: Hermes Agent-license: MIT-metadata:- hermes:- tags: [short, descriptive, tags]- related_skills: [other-skill, another-skill]-----```--`version` / `author` / `license` / `metadata` 不受验证器强制约束,但每个同类 skill 都有这些字段——省略会使你的 skill 显得格格不入。--## 大小限制--- Description:≤ 1024 个字符(强制执行)。-- 完整 SKILL.md:≤ 100,000 个字符(强制执行为 `MAX_SKILL_CONTENT_CHARS`,约 36k token)。-- `software-development/` 中的同类 skill 大小在 **8-14k 字符**之间。以此为目标范围。若超过 20k,请拆分为 `references/*.md` 并在 SKILL.md 中引用。--## 对等匹配结构--每个仓库内 skill 大致遵循以下结构:--```-# <Title>--## Overview-One or two paragraphs: what and why.--## When to Use-- Bulleted triggers-- "Don't use for:" counter-triggers--## <Topic sections specific to the skill>-- Quick-reference tables are common-- Code blocks with exact commands-- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)--## Common Pitfalls-Numbered list of mistakes and their fixes.--## Verification Checklist-- [ ] Checkbox list of post-action verifications--## One-Shot Recipes (optional)-Named scenarios → concrete command sequences.-```--并非每个章节都是必需的,但 `Overview` + `When to Use` + 可操作正文 + 常见问题至少要有,skill 才能与同类看齐。--## 目录放置--```-skills/<category>/<skill-name>/SKILL.md-```--仓库中现有的分类(通过 `ls skills/` 确认):`autonomous-ai-agents`、`creative`、`data-science`、`devops`、`email`、`gaming`、`github`、`leisure`、`mcp`、`media`、`mlops/*`、`note-taking`、`productivity`、`red-teaming`、`research`、`smart-home`、`social-media`、`software-development`。--选择最接近的现有分类。不要随意创建新的顶级分类。--## 工作流--1. **调查同类 skill**,位于目标分类下:- ```- ls skills/<category>/- ```- 阅读 2-3 个同类 SKILL.md 文件,以匹配语气和结构。-2. **如有疑问,检查 `tools/skill_manager_tool.py` 中的验证器约束。**-3. **起草**,使用 `write_file` 写入 `skills/<category>/<name>/SKILL.md`。-4. **本地验证**:- ```python- import re, pathlib- from ruamel.yaml import YAML- content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()- assert content.startswith("---")- m = re.search(r'\n---\s*\n', content[3:])- fm = YAML(typ="safe").load(content[3:m.start()+3])- assert "name" in fm and "description" in fm- assert len(fm["description"]) <= 1024- assert len(content) <= 100_000- ```-5. **Git add + commit**,在当前活跃分支上。-6. **注意:** 当前会话的 skill 加载器已缓存——`skill_view` / `skills_list` 在新会话开始前不会看到新 skill。这是预期行为,不是 bug。--## 交叉引用其他 Skill--`metadata.hermes.related_skills` 在加载时会合并两个目录树(仓库内 `skills/` 和 `~/.hermes/skills/`)。你**可以**从仓库内 skill 引用用户本地 skill,但对于全新克隆仓库的其他用户,该引用无法解析。仓库内 skill 优先只引用仓库内 skill。如果某个频繁被引用的 skill 仅存在于 `~/.hermes/skills/`,请考虑将其提升到仓库中。--## 编辑现有仓库内 Skill--- **小改动(修正错别字、添加常见问题、收紧触发条件):** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` 对仓库内 skill 同样有效。-- **大规模重写:** 使用 `write_file` 写入完整 SKILL.md。`skill_manage(action='edit')` 也可以,但需要提供完整的新内容。-- **添加支持文件:** 使用 `write_file` 写入 `skills/<category>/<name>/references/<file>.md`、`templates/<file>` 或 `scripts/<file>`。`skill_manage(action='write_file')` 也可以,并会强制执行 references/templates/scripts/assets 子目录白名单。-- **始终提交**编辑——仓库内 skill 是源码,不是运行时状态。--## 常见问题--1. **对仓库内 skill 使用 `skill_manage(action='create')`。** 它会写入 `~/.hermes/skills/`,而非仓库目录树。仓库内创建请使用 `write_file`。--2. **`---` 前有前导空白。** 验证器检查 `content.startswith("---")`;任何前导空行或 BOM 都会导致验证失败。--3. **Description 过于泛泛。** 同类 skill 的 description 以"Use when ..."开头,描述的是*触发类别*,而非单一任务。"Use when debugging X" 优于 "Debug X"。--4. **忘记添加 author/license/metadata 块。** 验证器不强制要求,但每个同类 skill 都有;省略会使 skill 看起来未完成。--5. **编写了与同类重复的 skill。** 创建前先执行 `ls skills/<category>/` 并打开 2-3 个同类 skill。优先扩展现有 skill,而非创建功能狭窄的兄弟 skill。--6. **期望当前会话能看到新 skill。** 不会。skill 加载器在会话开始时初始化。请在新会话中验证,或通过 `skill_view` 使用精确路径进行验证。--7. **链接到仓库中不存在的 skill。** `related_skills: [some-user-local-skill]` 对你有效,但对其他克隆用户会失效。优先只使用仓库内链接。--## 验证清单--- [ ] 文件位于 `skills/<category>/<name>/SKILL.md`(不在 `~/.hermes/skills/` 中)-- [ ] Frontmatter 从字节 0 以 `---` 开头,以 `\n---\n` 结束-- [ ] `name`、`description`、`version`、`author`、`license`、`metadata.hermes.{tags, related_skills}` 均已填写-- [ ] Name ≤ 64 个字符,小写加连字符-- [ ] Description ≤ 1024 个字符,且以"Use when ..."开头-- [ ] 文件总大小 ≤ 100,000 个字符(目标 8-15k)-- [ ] 结构:`# Title` → `## Overview` → `## When to Use` → 正文 → `## Common Pitfalls` → `## Verification Checklist`-- [ ] `related_skills` 中的引用在仓库内可解析(或明确允许为用户本地)-- [ ] 已在目标分支上完成 `git add skills/<category>/<name>/ && git commit`\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.mddeleted file mode 100644index 00d897b3ac5..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md+++ /dev/null@@ -1,337 +0,0 @@-----title: "Node Inspect 调试器 — 调试 Node"-sidebar_label: "Node Inspect 调试器"-description: "调试 Node"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Node Inspect 调试器--通过 --inspect + Chrome DevTools Protocol CLI 调试 Node.js。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/software-development/node-inspect-debugger` |-| 版本 | `1.0.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos, windows |-| 标签 | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |-| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。-:::--# Node.js Inspect 调试器--## 概述--当 `console.log` 不够用时,可以从终端以编程方式驱动 Node 内置的 V8 inspector。你可以使用真正的断点、单步执行(step in/over/out)、调用栈遍历、局部变量/闭包作用域转储,以及在暂停帧中执行任意表达式求值。--两种工具,选其一:--- **`node inspect`** — 内置,无需安装,CLI REPL(交互式命令行)。适合快速探查。-- **`ndb` / CDP via `chrome-remote-interface`** — 可从 Node/Python 脚本化调用;适合需要自动化设置大量断点、跨多次运行收集状态,或在 agent 循环中非交互式调试的场景。--**优先使用 `node inspect`。** 它始终可用,REPL 响应快。--## 使用时机--- Node 测试失败,需要查看中间状态-- ui-tui 崩溃或行为异常,需要在渲染前检查 React/Ink 状态-- tui_gateway 子进程(`_SlashWorker`、PTY bridge workers)行为异常-- 需要检查闭包中某个值,而不打补丁就无法用 `console.log` 获取-- 性能分析:附加到运行中的进程以采集 CPU profile 或堆快照--**不适用于:** 一分钟内用 `console.log` 就能解决的问题。断点调试开销较大,只在收益明显时使用。--## 快速参考:`node inspect` REPL--在第一行暂停启动:--```bash-node inspect path/to/script.js-# or with tsx-node --inspect-brk $(which tsx) path/to/script.ts-```--`debug>` 提示符接受以下命令:--| 命令 | 操作 |-|---|---|-| `c` 或 `cont` | 继续执行 |-| `n` 或 `next` | 单步跳过 |-| `s` 或 `step` | 单步进入 |-| `o` 或 `out` | 单步跳出 |-| `pause` | 暂停运行中的代码 |-| `sb('file.js', 42)` | 在 file.js 第 42 行设置断点 |-| `sb(42)` | 在当前文件第 42 行设置断点 |-| `sb('functionName')` | 在函数被调用时中断 |-| `cb('file.js', 42)` | 清除断点 |-| `breakpoints` | 列出所有断点 |-| `bt` | 回溯(调用栈) |-| `list(5)` | 显示当前位置前后各 5 行源码 |-| `watch('expr')` | 每次暂停时求值 expr |-| `watchers` | 显示监视表达式 |-| `repl` | 在当前作用域进入 REPL(Ctrl+C 退出 REPL) |-| `exec expr` | 单次求值表达式 |-| `restart` | 重启脚本 |-| `kill` | 终止脚本 |-| `.exit` | 退出调试器 |--**在 `repl` 子模式中:** 输入任意 JS 表达式,包括访问局部变量/闭包变量。`Ctrl+C` 返回 `debug>`。--## 附加到运行中的进程--当进程已在运行时(例如长期运行的开发服务器或 TUI gateway):--```bash-# 1. Send SIGUSR1 to enable the inspector on an existing process-kill -SIGUSR1 <pid>-# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid>--# 2. Attach the debugger CLI-node inspect -p <pid>-# or by URL-node inspect ws://127.0.0.1:9229/<uuid>-```--从一开始就启动带 inspector 的进程:--```bash-node --inspect script.js # listen on 127.0.0.1:9229, keep running-node --inspect-brk script.js # listen AND pause on first line-node --inspect=0.0.0.0:9230 script.js # custom host:port-```--通过 tsx 调试 TypeScript:--```bash-node --inspect-brk --import tsx script.ts-# or older tsx-node --inspect-brk -r tsx/cjs script.ts-```--## 程序化 CDP(从终端脚本化)--当需要自动化操作时——设置大量断点、捕获作用域状态、编写复现脚本——使用 `chrome-remote-interface`:--```bash-npm i -g chrome-remote-interface # or project-local-# Start your target:-node --inspect-brk=9229 target.js &-```--驱动脚本(保存为 `/tmp/cdp-debug.js`):--```javascript-const CDP = require('chrome-remote-interface');--(async () => {- const client = await CDP({ port: 9229 });- const { Debugger, Runtime } = client;-- Debugger.paused(async ({ callFrames, reason }) => {- const top = callFrames[0];- console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`);-- // Walk scopes for locals- for (const scope of top.scopeChain) {- if (scope.type === 'local' || scope.type === 'closure') {- const { result } = await Runtime.getProperties({- objectId: scope.object.objectId,- ownProperties: true,- });- for (const p of result) {- console.log(` ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description);- }- }- }-- // Evaluate an expression in the paused frame- const { result } = await Debugger.evaluateOnCallFrame({- callFrameId: top.callFrameId,- expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"',- });- console.log('state =', result.value ?? result.description);-- await Debugger.resume();- });-- await Runtime.enable();- await Debugger.enable();-- // Set a breakpoint by URL regex + line- await Debugger.setBreakpointByUrl({- urlRegex: '.*app\\.tsx$',- lineNumber: 119, // 0-indexed- columnNumber: 0,- });-- await Runtime.runIfWaitingForDebugger();-})();-```--运行:--```bash-node /tmp/cdp-debug.js-```--Hermes 专项说明:`chrome-remote-interface` 不在 `ui-tui/package.json` 中。如果不想污染项目,可将其安装到临时目录:--```bash-mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface-NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js-```--## 调试 Hermes ui-tui--TUI 基于 Ink + tsx 构建。两种常见场景:--### 在开发模式下调试单个 Ink 组件--`ui-tui/package.json` 有 `npm run dev`(tsx --watch)。直接运行 tsx 并添加 `--inspect-brk`:--```bash-cd /home/bb/hermes-agent/ui-tui-npm run build # produce dist/ once so transpile isn't needed on first load-node --inspect-brk dist/entry.js-# In another terminal:-node inspect -p <node pid>-```--然后在 `debug>` 中:--```-sb('dist/app.js', 220) # or wherever the suspect render is-cont-```--暂停后,进入 `repl` → 检查 `props`、state 引用、`useInput` 处理器的值等。--### 调试运行中的 `hermes --tui`--TUI 由 Python CLI 启动 Node。最简路径:--```bash-# 1. Launch TUI-hermes --tui &-TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1)--# 2. Enable inspector on that Node PID-kill -SIGUSR1 "$TUI_PID"--# 3. Find the WS URL-curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl'--# 4. Attach-node inspect ws://127.0.0.1:9229/<uuid>-```--在 TUI 窗口中交互(输入内容)会继续推进执行;调试器可以在任意 `sb(...)` 处暂停它。--### 调试 `_SlashWorker` / PTY 子进程--这些是 Python 进程,不是 Node——请使用 `python-debugpy` skill。只有 Node 部分(Ink UI、tui_gateway client、`ui-tui/` 下的 tsx-run 测试)使用本 skill。--## 在调试器下运行 Vitest 测试--```bash-cd /home/bb/hermes-agent/ui-tui-# Run a single test file paused on entry-node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx-```--在另一个终端:`node inspect -p <pid>`,然后 `sb('src/app/foo.tsx', 42)`,`cont`。--使用 `--no-file-parallelism`(vitest)或 `--runInBand`(jest),确保只有一个 worker——调试 worker 池非常痛苦。--## 堆快照与 CPU Profile(非交互式)--在上面的 CDP 驱动脚本中,将 Debugger 替换为 `HeapProfiler` / `Profiler`:--```javascript-// CPU profile for 5 seconds-await client.Profiler.enable();-await client.Profiler.start();-await new Promise(r => setTimeout(r, 5000));-const { profile } = await client.Profiler.stop();-require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile));-// Open /tmp/cpu.cpuprofile in Chrome DevTools → Performance tab-```--```javascript-// Heap snapshot-await client.HeapProfiler.enable();-const chunks = [];-client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk));-await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false });-require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join(''));-```--## 常见陷阱--1. **TS 源码行号错误。** 断点命中的是编译后的 JS,而非 `.ts` 文件。解决方案:(a)在构建产物 `dist/*.js` 中设置断点,或(b)启用 sourcemap(`node --enable-source-maps`)并使用 `sb('src/app.tsx', N)` — 但仅限于支持 sourcemap 的 CDP 客户端。`node inspect` CLI 不支持。--2. **`--inspect` 与 `--inspect-brk` 的区别。** `--inspect` 启动 inspector 但不暂停;如果附加太晚,脚本会在你设置第一个断点之前就跑完。需要在任何代码运行前设置断点时,使用 `--inspect-brk`。--3. **端口冲突。** 默认端口为 `9229`。如果多个 Node 进程同时开启 inspector,传入 `--inspect=0`(随机端口)并从 `/json/list` 读取实际 URL:- ```bash- curl -s http://127.0.0.1:9229/json/list # lists all inspectable targets on the host- ```--4. **子进程。** 父进程上的 `--inspect` 不会 inspect 其子进程。使用 `NODE_OPTIONS='--inspect-brk' node parent.js` 将其传播到每个子进程;注意它们都需要唯一端口(继承 `NODE_OPTIONS='--inspect'` 时 Node 会自动递增端口号)。--5. **后台进程被杀死。** 在目标进程暂停时 `Ctrl+C` 退出 `node inspect`,目标进程会保持暂停状态。请先执行 `cont`,或显式 `kill` 目标进程。--6. **在 agent 终端中运行 `node inspect`。** 它是一个 PTY 友好的 REPL。在 Hermes 中,使用 `terminal(pty=true)` 或 `background=true` + `process(action='submit', data='...')` 启动它。非 PTY 前台模式适用于单次命令,但不适合交互式单步调试。--7. **安全性。** `--inspect=0.0.0.0:9229` 会暴露任意代码执行能力。除非处于隔离网络,否则始终绑定到 `127.0.0.1`(默认值)。--## 验证清单--建立调试会话后,验证以下内容:--- [ ] `curl -s http://127.0.0.1:9229/json/list` 返回的正是预期目标-- [ ] 第一个断点确实命中(若未命中,可能是漏加了 `--inspect-brk`,或附加时执行已完成)-- [ ] 暂停时的源码列表显示正确文件(不匹配 = sourcemap 问题,见陷阱 1)-- [ ] 在 `repl` 中执行 `exec process.pid` 返回你想附加的 PID--## 一键配方--**"为什么这个变量在第 X 行是 undefined?"**-```bash-node --inspect-brk script.js &-node inspect -p $!-# debug>-sb('script.js', X)-cont-# paused. Now:-repl-> myVariable-> Object.keys(this)-```--**"进入这个函数的调用路径是什么?"**-```-debug> sb('suspectFn')-debug> cont-# paused on entry-debug> bt-```--**"这个 async 链挂住了——在哪里?"**-```-# Start with --inspect (no -brk), let it run to the hang, then:-debug> pause-debug> bt-# Now you see the stuck frame-```\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.mddeleted file mode 100644index de00b400349..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-python-debugpy.md+++ /dev/null@@ -1,400 +0,0 @@-----title: "Python Debugpy — 调试 Python:pdb REPL + debugpy 远程(DAP)"-sidebar_label: "Python Debugpy"-description: "调试 Python:pdb REPL + debugpy 远程(DAP)"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Python Debugpy--调试 Python:pdb REPL + debugpy 远程(DAP)。--## Skill 元数据--| | |-|---|---|-| 来源 | 内置(默认安装) |-| 路径 | `skills/software-development/python-debugpy` |-| 版本 | `1.0.0` |-| 作者 | Hermes Agent |-| 许可证 | MIT |-| 平台 | linux, macos |-| 标签 | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |-| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# Python 调试器(pdb + debugpy)--## 概述--三种工具,按场景选择:--| 工具 | 适用场景 |-|---|---|-| **`breakpoint()` + pdb** | 本地、交互式、最简单。在源码中添加 `breakpoint()`,正常运行,在该行进入 REPL。 |-| **`python -m pdb`** | 无需修改源码,直接在 pdb 下启动已有脚本。适合快速探查。 |-| **`debugpy`** | 远程 / 无头 / "附加到已运行进程"。使用 DAP 协议,可从终端脚本化操作,适用于长期运行的进程(gateway、daemon、PTY 子进程)。 |--**从 `breakpoint()` 开始。** 这是最低成本的可行方案。--## 使用时机--- 测试失败,但 traceback 无法说明某个值为何出错-- 需要逐步执行某个函数并观察集合的变化-- 长期运行的进程(hermes gateway、tui_gateway)出现异常且无法重启-- 事后分析(post-mortem):异常在类生产代码中触发,需要检查崩溃现场的局部变量-- 子进程 / 子进程(Python `_SlashWorker`、PTY bridge worker)才是实际的 bug 所在--**不适用于:** `print()` / `logging.debug` 一分钟内能解决的问题,或 `pytest -vv --tb=long --showlocals` 已经能揭示的问题。--## pdb 快速参考--在任意 pdb 提示符(`(Pdb)`)下:--| 命令 | 操作 |-|---|---|-| `h` / `h cmd` | 帮助 |-| `n` | 下一行(步过) |-| `s` | 步入 |-| `r` | 从当前函数返回 |-| `c` | 继续执行 |-| `unt N` | 继续执行直到第 N 行 |-| `j N` | 跳转到第 N 行(仅限同一函数) |-| `l` / `ll` | 列出当前行附近的源码 / 完整函数 |-| `w` | 当前位置(调用栈跟踪) |-| `u` / `d` | 在调用栈中上移 / 下移 |-| `a` | 打印当前函数的参数 |-| `p expr` / `pp expr` | 打印 / 格式化打印表达式 |-| `display expr` | 每次停止时自动打印 expr |-| `b file:line` | 设置断点 |-| `b func` | 在函数入口处断点 |-| `b file:line, cond` | 条件断点 |-| `cl N` | 清除断点 N |-| `tbreak file:line` | 一次性断点 |-| `!stmt` | 执行任意 Python 语句(包括赋值) |-| `interact` | 在当前作用域中进入完整 Python REPL(Ctrl+D 退出) |-| `q` | 退出 |--`interact` 命令最为强大——可以导入任何模块、检查复杂对象,甚至调用会改变状态的方法。局部变量默认只读;在 `(Pdb)` 提示符下使用 `!x = 42` 进行修改。--## 方案 1:本地断点--最简单。编辑文件:--```python-def compute(x, y):- result = some_helper(x)- breakpoint() # <-- 在此处进入 pdb- return result + y-```--正常运行代码。你将在 `breakpoint()` 所在行停下,可完整访问局部变量。--**提交前务必删除 `breakpoint()`。** 使用 `git diff` 或 pre-commit grep:-```bash-rg -n 'breakpoint\(\)' --type py-```--## 方案 2:在 pdb 下启动脚本(无需修改源码)--```bash-python -m pdb path/to/script.py arg1 arg2-# 停在脚本第一行-(Pdb) b path/to/script.py:42-(Pdb) c-```--## 方案 3:调试 pytest 测试--通过 `terminal` 使用标准测试运行器进行非交互诊断:--```bash-# 在 traceback 中显示局部变量,不使用 pdb:-scripts/run_tests.sh tests/path/to/test_file.py --showlocals --tb=long-```--`scripts/run_tests.sh` 捕获每个文件的子进程输出,无法提供交互式 `--pdb` 或 `--trace`-提示符。仅在交互调试时使用方案 5 准备的独立开发/测试解释器,不要使用生产环境:--```bash-.venv/bin/python -m pytest tests/foo_test.py::test_bar --pdb-```--这会绕过封闭环境保证——调试时可以接受,但推送前请在 wrapper 下重新运行以确认。--## 方案 4:对任意异常进行事后分析--```python-import pdb, sys-try:- run_the_thing()-except Exception:- pdb.post_mortem(sys.exc_info()[2])-```--或对整个脚本进行包装:--```bash-python -m pdb -c continue script.py-# 崩溃时,pdb 捕获异常并停在异常所在帧-```--或在 repl/jupyter 中设置全局 hook:--```python-import sys-def excepthook(etype, value, tb):- import pdb; pdb.post_mortem(tb)-sys.excepthook = excepthook-```--## 方案 5:使用 debugpy 进行远程调试(附加到运行中的进程)--适用于长期运行的进程:Hermes gateway、tui_gateway、daemon,或已出现异常且无法干净重启的进程。--### 安装--使用独立开发检出和数据目录,不要修改正在运行的生产环境。-按照 [PM 开发流程](https://hermes-agent.nousresearch.com/docs/reference/package-management#developer-workflow)-激活该检出——PowerShell 使用 `. .\activate.ps1`。`dev` extra 已包含 debugpy,-但 PM 激活不会同步它(`all` 不含该 extra)。通过 `terminal`,用该检出准备好的-Python 构建全新的调试/测试环境:--```bash-source ./activate-python -m pm.build_env --source . --out .venv --group dev --group test-.venv/bin/python -c "import debugpy; print(debugpy.__file__)"-```--输出目录必须不存在。重建前停止其进程,并明确删除仅用于调试的可丢弃环境。-调试目标使用相同的独立 `HERMES_HOME`。`.venv/bin/python` 就是刚构建的独立环境,-不是猜测的应用 venv,下面的模式都通过它运行。不要向正在运行的生产环境安装-debugpy;请在准备好的调试目标复现,或安排在开发环境重启。--### 模式 A:修改源码——进程在启动时等待调试器--在入口点顶部附近(或要调试的函数内部)添加:--```python-import debugpy-debugpy.listen(("127.0.0.1", 5678))-print("debugpy listening on 5678, waiting for client...", flush=True)-debugpy.wait_for_client()-debugpy.breakpoint() # 可选:附加后立即暂停-```--启动进程;它将阻塞在 `wait_for_client()`。--### 模式 B:无需修改源码——使用 `-m debugpy` 启动--```bash-.venv/bin/python -m debugpy --listen 127.0.0.1:5678 --wait-for-client your_script.py arg1-```--模块入口的等效写法:--```bash-.venv/bin/python -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m your.module-```--### 模式 C:附加到已运行的进程--需要 PID 以及在目标环境中预装 debugpy:--```bash-.venv/bin/python -m debugpy --listen 127.0.0.1:5678 --pid <pid>-# debugpy 注入到目标进程中,然后按以下方式连接客户端。-```--某些内核 / 安全配置会阻止基于 ptrace 的注入(`/proc/sys/kernel/yama/ptrace_scope`)。修复方法:-```bash-echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope-```--### 从终端连接客户端--最简便的终端侧 DAP 客户端是 VS Code CLI 或一个小脚本。在 Hermes 内部有两个实用选项:--**选项 1:`debugpy` 自带 CLI REPL** — 并非官方功能,而是一个小型 DAP 客户端脚本:--```python-# /tmp/dap_client.py-import socket, json, itertools, time, sys--HOST, PORT = "127.0.0.1", 5678-s = socket.create_connection((HOST, PORT))-seq = itertools.count(1)--def send(msg):- msg["seq"] = next(seq)- body = json.dumps(msg).encode()- s.sendall(f"Content-Length: {len(body)}\r\n\r\n".encode() + body)--def recv():- header = b""- while b"\r\n\r\n" not in header:- header += s.recv(1)- length = int(header.decode().split("Content-Length:")[1].split("\r\n")[0].strip())- body = b""- while len(body) < length:- body += s.recv(length - len(body))- return json.loads(body)--send({"type": "request", "command": "initialize", "arguments": {"adapterID": "python"}})-print(recv())-send({"type": "request", "command": "attach", "arguments": {}})-print(recv())-send({"type": "request", "command": "setBreakpoints",- "arguments": {"source": {"path": sys.argv[1]},- "breakpoints": [{"line": int(sys.argv[2])}]}})-print(recv())-send({"type": "request", "command": "configurationDone"})-# ... 循环读取事件并发送 continue/stepIn 等命令-```--用于一次性自动化尚可,但作为交互式 UX 体验较差。--**选项 2:从 VS Code / Cursor / Zed 附加** — 如果用户已打开其中一个,可添加 `launch.json`:--```json-{- "name": "Attach to Hermes",- "type": "debugpy",- "request": "attach",- "connect": { "host": "127.0.0.1", "port": 5678 },- "justMyCode": false,- "pathMappings": [- { "localRoot": "${workspaceFolder}", "remoteRoot": "<hermes-agent-repo>" }- ]-}-```--**选项 3:放弃 DAP,使用 `remote-pdb`** — 通常这才是终端 agent 真正需要的:--独立 Python 项目可以在其开发依赖中声明 `remote-pdb`,再用该项目的包管理器-准备调试环境。这不是 Hermes SDK 安装方法。Hermes 优先使用已声明的 debugpy;-下面的 remote-pdb 示例需要另行声明并全新构建的调试环境,绝不能向选中的应用环境-原地 pip 安装。--在代码中:-```python-from remote_pdb import set_trace-set_trace(host="127.0.0.1", port=4444) # 阻塞直到连接-```--然后在终端中:-```bash-nc 127.0.0.1 4444-# 获得一个 (Pdb) 提示符,与本地调试完全一致。-```--当 `debugpy` 的 DAP 协议过于繁重时,`remote-pdb` 是最适合 agent 的选择。仅在确实需要 IDE 集成时才使用 `debugpy`。--## 调试 Hermes 特定进程--### 测试-参见方案 3。wrapper 会捕获子进程输出,交互式 pdb 请直接运行 pytest。--### `run_agent.py` / CLI — 一次性运行-在准备好的调试检出中,在可疑行附近添加 `breakpoint()`,然后运行 `python hermes`。-控制权将在暂停点返回到你的终端。--### `tui_gateway` 子进程(由 `hermes --tui` 启动)-gateway 作为 Node TUI 的子进程运行。可选方案:--**A. 修改 gateway 源码:**-```python-# tui_gateway/server.py,在 serve() 顶部附近-import debugpy-debugpy.listen(("127.0.0.1", 5678))-debugpy.wait_for_client()-```-从准备好的调试检出启动 `python hermes --tui`。TUI 将显示为冻结状态(其后端正在等待)。-附加客户端后,执行在你 `continue` 时恢复。先检查子进程的解释器和导入路径,-不要假定它继承了调试环境。--**B. 在特定处理器中使用 `remote-pdb`:**-```python-from remote_pdb import set_trace-set_trace(host="127.0.0.1", port=4444) # 在你想捕获的 RPC 处理器中-```-从 TUI 触发对应的 slash 命令,然后在另一个终端中执行 `nc 127.0.0.1 4444`。--### `_SlashWorker` 子进程-相同模式——在 worker 的 `exec` 路径中使用 `remote-pdb` 的 `set_trace()`。该 worker 在多次 slash 命令间持续存在,因此第一次触发会阻塞直到你连接;后续 slash 命令正常通过,除非你重新设置断点。--### Gateway(`gateway/run.py`)-长期运行。在处理器中使用 `remote-pdb`,或者如果你本来就要重启 gateway,则使用带 `--wait-for-client` 的 `debugpy`。--## 常见陷阱--1. **pdb 在并行/捕获输出的 runner 下静默失效。** 你不会看到提示符,测试只会挂起(pytest-xdist 与 `scripts/run_tests.sh` 的按文件捕获子进程均如此)。交互式调试请直接对单个文件运行 pytest。--2. **`breakpoint()` 在 CI / 非 TTY 环境中会挂起进程。** 本地使用没问题;永远不要提交它。添加 pre-commit grep 作为安全网。--3. **`PYTHONBREAKPOINT=0`** 会禁用所有 `breakpoint()` 调用。如果断点未触发,请检查环境变量:- ```bash- echo $PYTHONBREAKPOINT- ```--4. **`debugpy.listen` 仅在同时调用 `wait_for_client()` 时才会阻塞。** 不调用的话,执行会继续,你的第一个断点可能在客户端附加之前就已触发。--5. **在加固内核上附加到 PID 会失败。** `ptrace_scope=1`(Ubuntu 默认值)仅允许对同用户的子进程进行 ptrace。解决方法:`echo 0 > /proc/sys/kernel/yama/ptrace_scope`(需要 root 权限),或从一开始就在 `debugpy` 下启动。--6. **线程。** `pdb` 只调试当前线程。对于多线程代码,使用 `debugpy`(支持线程感知的 DAP)或为每个线程设置 `threading.settrace()`。--7. **asyncio。** `pdb` 可在协程中工作,但在 pdb 内部使用 `await` 需要 Python 3.13+ 或在旧版本的 `interact` 模式下使用 `await`。对于 3.11/3.12,使用 `asyncio.run_coroutine_threadsafe` 技巧,或通过 `asyncio.ensure_future` 配合 `!stmt` 方式进行 await。--8. **`scripts/run_tests.sh` 会剥离凭据并设置 `HOME=<tmpdir>`。** 如果你的 bug 依赖用户配置或真实 API 密钥,在 wrapper 下将无法复现。先用原始 `pytest` 复现,再在 wrapper 下确认。--9. **fork / 多进程。** pdb 不会跟随 fork。每个子进程需要自己的 `breakpoint()` 或 `set_trace()`。对于 Hermes 子 agent,每次只调试一个进程。--## 验证清单--- [ ] 在独立构建的调试环境中确认:`.venv/bin/python -c "import debugpy; print(debugpy.__version__); print(debugpy.__file__)"`-- [ ] 对于远程调试,确认端口确实在监听:`ss -tlnp | grep 5678`-- [ ] 第一个断点确实触发(如果没有,可能是 `PYTHONBREAKPOINT=0`、在并行/捕获输出的 runner 下运行,或执行在附加前已结束)-- [ ] `where` / `w` 显示预期的调用栈-- [ ] 调试后清理:已提交代码中无残留的 `breakpoint()` / `set_trace()` / `debugpy.listen`- ```bash- rg -n 'breakpoint\(\)|set_trace\(|debugpy\.listen' --type py- ```--## 一次性速查方案--**"为什么这个 dict 缺少某个键?"**-```python-# 在 KeyError 发生处上方添加-breakpoint()-# 然后在 pdb 中:-(Pdb) pp d-(Pdb) pp list(d.keys())-(Pdb) w # 我们是怎么到这里的-```--**"这个测试单独运行通过,但在测试套件中失败。"**-```bash-scripts/run_tests.sh tests/the_test.py # 先确认它在隔离 runner 下失败-# 交互式调试,或只有与其他测试一起运行才失败时,使用 Recipe 5 准备的独立开发/测试解释器:-.venv/bin/python -m pytest tests/ -x --pdb-# 现在它会在状态积累后的确切失败测试处触发 pdb。-```--**"我的异步处理器发生死锁。"**-```python-# 在处理器入口处添加-import remote_pdb; remote_pdb.set_trace(host="127.0.0.1", port=4444)-```-触发处理器。执行 `nc 127.0.0.1 4444`,然后用 `w` 查看挂起的帧,用 `!import asyncio; asyncio.all_tasks()` 查看其他待处理任务。--**"对 Ink 子进程 / subprocess 中的崩溃进行事后分析。"**-```bash-PYTHONFAULTHANDLER=1 python -m pdb -c continue path/to/entrypoint.py-# 崩溃时,pdb 停在异常所在帧,可访问完整局部变量-```\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.mddeleted file mode 100644index 225c3164593..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md+++ /dev/null@@ -1,588 +0,0 @@-----title: "Audiocraft 音频生成 — AudioCraft:MusicGen 文本转音乐,AudioGen 文本转声音"-sidebar_label: "Audiocraft 音频生成"-description: "AudioCraft:MusicGen 文本转音乐,AudioGen 文本转声音"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Audiocraft 音频生成--AudioCraft:MusicGen 文本转音乐,AudioGen 文本转声音。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/creative/audiocraft-audio-generation` 安装 |-| 路径 | `optional-skills/creative/audiocraft-audio-generation` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖 | `audiocraft`, `torch>=2.0.0`, `transformers>=4.30.0` |-| 平台 | linux, macos |-| 标签 | `Multimodal`, `Audio Generation`, `Text-to-Music`, `Text-to-Audio`, `MusicGen` |-| 相关 skill | [`heartmula`](/user-guide/skills/optional/creative/creative-heartmula), [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# AudioCraft:音频生成--使用 Meta 的 AudioCraft 进行文本转音乐和文本转音频生成的完整指南,涵盖 MusicGen、AudioGen 和 EnCodec。--## 何时使用 AudioCraft--**在以下情况下使用 AudioCraft:**-- 需要从文本描述生成音乐-- 创建音效和环境音频-- 构建音乐生成应用-- 需要旋律条件化的音乐生成-- 需要立体声音频输出-- 需要可控的风格迁移音乐生成--**核心功能:**-- **MusicGen**:支持旋律条件化的文本转音乐生成-- **AudioGen**:文本转音效生成-- **EnCodec**:高保真神经音频编解码器-- **多种模型规格**:从 Small(300M)到 Large(3.3B)-- **立体声支持**:完整立体声音频生成-- **风格条件化**:MusicGen-Style 支持基于参考的生成--**以下情况请使用替代方案:**-- **Stable Audio**:用于较长的商业音乐生成-- **Bark**:用于带音乐/音效的文本转语音-- **Riffusion**:用于基于频谱图的音乐生成-- **OpenAI Jukebox**:用于带歌词的原始音频生成--## 快速开始--### 安装--```bash-# 从 PyPI 安装-pip install audiocraft--# 从 GitHub 安装(最新版)-pip install git+https://github.com/facebookresearch/audiocraft.git--# 或使用 HuggingFace Transformers-pip install transformers torch torchaudio-```--### 基础文本转音乐(AudioCraft)--```python-import torchaudio-from audiocraft.models import MusicGen--# 加载模型-model = MusicGen.get_pretrained('facebook/musicgen-small')--# 设置生成参数-model.set_generation_params(- duration=8, # 秒- top_k=250,- temperature=1.0-)--# 从文本生成-descriptions = ["happy upbeat electronic dance music with synths"]-wav = model.generate(descriptions)--# 保存音频-torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)-```--### 使用 HuggingFace Transformers--```python-from transformers import AutoProcessor, MusicgenForConditionalGeneration-import scipy--# 加载模型和处理器-processor = AutoProcessor.from_pretrained("facebook/musicgen-small")-model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")-model.to("cuda")--# 生成音乐-inputs = processor(- text=["80s pop track with bassy drums and synth"],- padding=True,- return_tensors="pt"-).to("cuda")--audio_values = model.generate(- **inputs,- do_sample=True,- guidance_scale=3,- max_new_tokens=256-)--# 保存-sampling_rate = model.config.audio_encoder.sampling_rate-scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())-```--### 使用 AudioGen 进行文本转声音--```python-from audiocraft.models import AudioGen--# 加载 AudioGen-model = AudioGen.get_pretrained('facebook/audiogen-medium')--model.set_generation_params(duration=5)--# 生成音效-descriptions = ["dog barking in a park with birds chirping"]-wav = model.generate(descriptions)--torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)-```--## 核心概念--### 架构概览--<!-- ascii-guard-ignore -->-```-AudioCraft Architecture:-┌──────────────────────────────────────────────────────────────┐-│ Text Encoder (T5) │-│ │ │-│ Text Embeddings │-└────────────────────────┬─────────────────────────────────────┘- │-┌────────────────────────▼─────────────────────────────────────┐-│ Transformer Decoder (LM) │-│ Auto-regressively generates audio tokens │-│ Using efficient token interleaving patterns │-└────────────────────────┬─────────────────────────────────────┘- │-┌────────────────────────▼─────────────────────────────────────┐-│ EnCodec Audio Decoder │-│ Converts tokens back to audio waveform │-└──────────────────────────────────────────────────────────────┘-```-<!-- ascii-guard-ignore-end -->--### 模型变体--| 模型 | 规模 | 描述 | 适用场景 |-|-------|------|-------------|----------|-| `musicgen-small` | 300M | 文本转音乐 | 快速生成 |-| `musicgen-medium` | 1.5B | 文本转音乐 | 均衡选择 |-| `musicgen-large` | 3.3B | 文本转音乐 | 最佳质量 |-| `musicgen-melody` | 1.5B | 文本 + 旋律 | 旋律条件化 |-| `musicgen-melody-large` | 3.3B | 文本 + 旋律 | 最佳旋律效果 |-| `musicgen-stereo-*` | 不定 | 立体声输出 | 立体声生成 |-| `musicgen-style` | 1.5B | 风格迁移 | 基于参考的生成 |-| `audiogen-medium` | 1.5B | 文本转声音 | 音效生成 |--### 生成参数--| 参数 | 默认值 | 描述 |-|-----------|---------|-------------|-| `duration` | 8.0 | 时长(秒),范围 1-120 |-| `top_k` | 250 | Top-k 采样 |-| `top_p` | 0.0 | Nucleus 采样(0 = 禁用) |-| `temperature` | 1.0 | 采样温度 |-| `cfg_coef` | 3.0 | 无分类器引导系数 |--## MusicGen 用法--### 文本转音乐生成--```python-from audiocraft.models import MusicGen-import torchaudio--model = MusicGen.get_pretrained('facebook/musicgen-medium')--# 配置生成参数-model.set_generation_params(- duration=30, # 最长 30 秒- top_k=250, # 采样多样性- top_p=0.0, # 0 = 仅使用 top_k- temperature=1.0, # 创意度(越高越多样)- cfg_coef=3.0 # 文本遵循度(越高越严格)-)--# 生成多个样本-descriptions = [- "epic orchestral soundtrack with strings and brass",- "chill lo-fi hip hop beat with jazzy piano",- "energetic rock song with electric guitar"-]--# 生成(返回 [batch, channels, samples])-wav = model.generate(descriptions)--# 逐个保存-for i, audio in enumerate(wav):- torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000)-```--### 旋律条件化生成--```python-from audiocraft.models import MusicGen-import torchaudio--# 加载旋律模型-model = MusicGen.get_pretrained('facebook/musicgen-melody')-model.set_generation_params(duration=30)--# 加载旋律音频-melody, sr = torchaudio.load("melody.wav")--# 使用旋律条件化生成-descriptions = ["acoustic guitar folk song"]-wav = model.generate_with_chroma(descriptions, melody, sr)--torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000)-```--### 立体声生成--```python-from audiocraft.models import MusicGen--# 加载立体声模型-model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')-model.set_generation_params(duration=15)--descriptions = ["ambient electronic music with wide stereo panning"]-wav = model.generate(descriptions)--# wav 形状:立体声为 [batch, 2, samples]-print(f"Stereo shape: {wav.shape}") # [1, 2, 480000]-torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000)-```--### 音频续写--```python-from transformers import AutoProcessor, MusicgenForConditionalGeneration--processor = AutoProcessor.from_pretrained("facebook/musicgen-medium")-model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium")--# 加载待续写的音频-import torchaudio-audio, sr = torchaudio.load("intro.wav")--# 同时处理文本和音频-inputs = processor(- audio=audio.squeeze().numpy(),- sampling_rate=sr,- text=["continue with a epic chorus"],- padding=True,- return_tensors="pt"-)--# 生成续写内容-audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512)-```--## MusicGen-Style 用法--### 风格条件化生成--```python-from audiocraft.models import MusicGen--# 加载风格模型-model = MusicGen.get_pretrained('facebook/musicgen-style')--# 配置带风格的生成参数-model.set_generation_params(- duration=30,- cfg_coef=3.0,- cfg_coef_beta=5.0 # 风格影响强度-)--# 配置风格条件器参数-model.set_style_conditioner_params(- eval_q=3, # RVQ 量化器数量(1-6)- excerpt_length=3.0 # 风格片段长度-)--# 加载风格参考音频-style_audio, sr = torchaudio.load("reference_style.wav")--# 使用文本 + 风格生成-descriptions = ["upbeat dance track"]-wav = model.generate_with_style(descriptions, style_audio, sr)-```--### 仅风格生成(无文本)--```python-# 不使用文本 prompt,仅匹配风格生成-model.set_generation_params(- duration=30,- cfg_coef=3.0,- cfg_coef_beta=None # 禁用双 CFG 以支持纯风格模式-)--wav = model.generate_with_style([None], style_audio, sr)-```--## AudioGen 用法--### 音效生成--```python-from audiocraft.models import AudioGen-import torchaudio--model = AudioGen.get_pretrained('facebook/audiogen-medium')-model.set_generation_params(duration=10)--# 生成各类声音-descriptions = [- "thunderstorm with heavy rain and lightning",- "busy city traffic with car horns",- "ocean waves crashing on rocks",- "crackling campfire in forest"-]--wav = model.generate(descriptions)--for i, audio in enumerate(wav):- torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)-```--## EnCodec 用法--### 音频压缩--```python-from audiocraft.models import CompressionModel-import torch-import torchaudio--# 加载 EnCodec-model = CompressionModel.get_pretrained('facebook/encodec_32khz')--# 加载音频-wav, sr = torchaudio.load("audio.wav")--# 确保采样率正确-if sr != 32000:- resampler = torchaudio.transforms.Resample(sr, 32000)- wav = resampler(wav)--# 编码为 token-with torch.no_grad():- encoded = model.encode(wav.unsqueeze(0))- codes = encoded[0] # 音频编码--# 解码回音频-with torch.no_grad():- decoded = model.decode(codes)--torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)-```--## 常见工作流--### 工作流 1:音乐生成流水线--```python-import torch-import torchaudio-from audiocraft.models import MusicGen--class MusicGenerator:- def __init__(self, model_name="facebook/musicgen-medium"):- self.model = MusicGen.get_pretrained(model_name)- self.sample_rate = 32000-- def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):- self.model.set_generation_params(- duration=duration,- top_k=250,- temperature=temperature,- cfg_coef=cfg- )-- with torch.no_grad():- wav = self.model.generate([prompt])-- return wav[0].cpu()-- def generate_batch(self, prompts, duration=30):- self.model.set_generation_params(duration=duration)-- with torch.no_grad():- wav = self.model.generate(prompts)-- return wav.cpu()-- def save(self, audio, path):- torchaudio.save(path, audio, sample_rate=self.sample_rate)--# 使用示例-generator = MusicGenerator()-audio = generator.generate(- "epic cinematic orchestral music",- duration=30,- temperature=1.0-)-generator.save(audio, "epic_music.wav")-```--### 工作流 2:音效批量处理--```python-import json-from pathlib import Path-from audiocraft.models import AudioGen-import torchaudio--def batch_generate_sounds(sound_specs, output_dir):- """- 根据规格批量生成声音。-- Args:- sound_specs: list of {"name": str, "description": str, "duration": float}- output_dir: output directory path- """- model = AudioGen.get_pretrained('facebook/audiogen-medium')- output_dir = Path(output_dir)- output_dir.mkdir(exist_ok=True)-- results = []-- for spec in sound_specs:- model.set_generation_params(duration=spec.get("duration", 5))-- wav = model.generate([spec["description"]])-- output_path = output_dir / f"{spec['name']}.wav"- torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)-- results.append({- "name": spec["name"],- "path": str(output_path),- "description": spec["description"]- })-- return results--# 使用示例-sounds = [- {"name": "explosion", "description": "massive explosion with debris", "duration": 3},- {"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},- {"name": "door", "description": "wooden door creaking and closing", "duration": 2}-]--results = batch_generate_sounds(sounds, "sound_effects/")-```--### 工作流 3:Gradio 演示--```python-import gradio as gr-import torch-import torchaudio-from audiocraft.models import MusicGen--model = MusicGen.get_pretrained('facebook/musicgen-small')--def generate_music(prompt, duration, temperature, cfg_coef):- model.set_generation_params(- duration=duration,- temperature=temperature,- cfg_coef=cfg_coef- )-- with torch.no_grad():- wav = model.generate([prompt])-- # 保存到临时文件- path = "temp_output.wav"- torchaudio.save(path, wav[0].cpu(), sample_rate=32000)- return path--demo = gr.Interface(- fn=generate_music,- inputs=[- gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),- gr.Slider(1, 30, value=8, label="Duration (seconds)"),- gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),- gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")- ],- outputs=gr.Audio(label="Generated Music"),- title="MusicGen Demo"-)--demo.launch()-```--## 性能优化--### 内存优化--```python-# 使用较小的模型-model = MusicGen.get_pretrained('facebook/musicgen-small')--# 每次生成后清理缓存-torch.cuda.empty_cache()--# 生成较短的时长-model.set_generation_params(duration=10) # 替代 30 秒--# 使用半精度-model = model.half()-```--### 批处理效率--```python-# 一次处理多个 prompt(更高效)-descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]-wav = model.generate(descriptions) # 单次批处理--# 而非-for desc in descriptions:- wav = model.generate([desc]) # 多次批处理(较慢)-```--### GPU 显存需求--| 模型 | FP32 显存 | FP16 显存 |-|-------|-----------|-----------|-| musicgen-small | ~4GB | ~2GB |-| musicgen-medium | ~8GB | ~4GB |-| musicgen-large | ~16GB | ~8GB |--## 常见问题--| 问题 | 解决方案 |-|-------|----------|-| CUDA 显存不足 | 使用较小模型,缩短时长 |-| 质量较差 | 提高 cfg_coef,优化 prompt |-| 生成时长过短 | 检查最大时长设置 |-| 音频有杂音 | 尝试不同的 temperature |-| 立体声不生效 | 使用立体声模型变体 |--## 参考资料--- **[高级用法](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/audiocraft/references/advanced-usage.md)** - 训练、微调、部署-- **[故障排查](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/models/audiocraft/references/troubleshooting.md)** - 常见问题与解决方案--## 资源--- **GitHub**:https://github.com/facebookresearch/audiocraft-- **论文(MusicGen)**:https://arxiv.org/abs/2306.05284-- **论文(AudioGen)**:https://arxiv.org/abs/2209.15352-- **HuggingFace**:https://huggingface.co/facebook/musicgen-small-- **演示**:https://huggingface.co/spaces/facebook/MusicGen\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-clip.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-clip.mddeleted file mode 100644index fa11acab438..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-clip.md+++ /dev/null@@ -1,272 +0,0 @@-----title: "Clip — OpenAI 连接视觉与语言的模型"-sidebar_label: "Clip"-description: "OpenAI 连接视觉与语言的模型"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Clip--OpenAI 连接视觉与语言的模型。支持零样本图像分类、图文匹配和跨模态检索。在 4 亿图文对上训练而成。可用于图像搜索、内容审核或视觉语言任务,无需微调。最适合通用图像理解场景。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/clip` 安装 |-| 路径 | `optional-skills/mlops/clip` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `transformers`, `torch`, `pillow` |-| 平台 | linux, macos, windows |-| 标签 | `Multimodal`, `CLIP`, `Vision-Language`, `Zero-Shot`, `Image Classification`, `OpenAI`, `Image Search`, `Cross-Modal Retrieval`, `Content Moderation` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# CLIP - 对比语言图像预训练(Contrastive Language-Image Pre-Training)--OpenAI 推出的能够通过自然语言理解图像的模型。--## 何时使用 CLIP--**适用场景:**-- 零样本图像分类(无需训练数据)-- 图文相似度/匹配-- 语义图像搜索-- 内容审核(检测 NSFW、暴力内容)-- 视觉问答-- 跨模态检索(图像→文本、文本→图像)--**指标**:-- **GitHub 25,300+ 星**-- 在 4 亿图文对上训练-- 零样本下在 ImageNet 上与 ResNet-50 持平-- MIT 许可证--**以下情况请使用替代方案**:-- **BLIP-2**:更好的图像描述生成-- **LLaVA**:视觉语言对话-- **Segment Anything**:图像分割--## 快速开始--### 安装--```bash-pip install git+https://github.com/openai/CLIP.git-pip install torch torchvision ftfy regex tqdm-```--### 零样本分类--```python-import torch-import clip-from PIL import Image--# Load model-device = "cuda" if torch.cuda.is_available() else "cpu"-model, preprocess = clip.load("ViT-B/32", device=device)--# Load image-image = preprocess(Image.open("photo.jpg")).unsqueeze(0).to(device)--# Define possible labels-text = clip.tokenize(["a dog", "a cat", "a bird", "a car"]).to(device)--# Compute similarity-with torch.no_grad():- image_features = model.encode_image(image)- text_features = model.encode_text(text)-- # Cosine similarity- logits_per_image, logits_per_text = model(image, text)- probs = logits_per_image.softmax(dim=-1).cpu().numpy()--# Print results-labels = ["a dog", "a cat", "a bird", "a car"]-for label, prob in zip(labels, probs[0]):- print(f"{label}: {prob:.2%}")-```--## 可用模型--```python-# Models (sorted by size)-models = [- "RN50", # ResNet-50- "RN101", # ResNet-101- "ViT-B/32", # Vision Transformer (recommended)- "ViT-B/16", # Better quality, slower- "ViT-L/14", # Best quality, slowest-]--model, preprocess = clip.load("ViT-B/32")-```--| 模型 | 参数量 | 速度 | 质量 |-|-------|------------|-------|---------|-| RN50 | 102M | 快 | 良好 |-| ViT-B/32 | 151M | 中等 | 更好 |-| ViT-L/14 | 428M | 慢 | 最佳 |--## 图文相似度--```python-# Compute embeddings-image_features = model.encode_image(image)-text_features = model.encode_text(text)--# Normalize-image_features /= image_features.norm(dim=-1, keepdim=True)-text_features /= text_features.norm(dim=-1, keepdim=True)--# Cosine similarity-similarity = (image_features @ text_features.T).item()-print(f"Similarity: {similarity:.4f}")-```--## 语义图像搜索--```python-# Index images-image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]-image_embeddings = []--for img_path in image_paths:- image = preprocess(Image.open(img_path)).unsqueeze(0).to(device)- with torch.no_grad():- embedding = model.encode_image(image)- embedding /= embedding.norm(dim=-1, keepdim=True)- image_embeddings.append(embedding)--image_embeddings = torch.cat(image_embeddings)--# Search with text query-query = "a sunset over the ocean"-text_input = clip.tokenize([query]).to(device)-with torch.no_grad():- text_embedding = model.encode_text(text_input)- text_embedding /= text_embedding.norm(dim=-1, keepdim=True)--# Find most similar images-similarities = (text_embedding @ image_embeddings.T).squeeze(0)-top_k = similarities.topk(3)--for idx, score in zip(top_k.indices, top_k.values):- print(f"{image_paths[idx]}: {score:.3f}")-```--## 内容审核--```python-# Define categories-categories = [- "safe for work",- "not safe for work",- "violent content",- "graphic content"-]--text = clip.tokenize(categories).to(device)--# Check image-with torch.no_grad():- logits_per_image, _ = model(image, text)- probs = logits_per_image.softmax(dim=-1)--# Get classification-max_idx = probs.argmax().item()-max_prob = probs[0, max_idx].item()--print(f"Category: {categories[max_idx]} ({max_prob:.2%})")-```--## 批量处理--```python-# Process multiple images-images = [preprocess(Image.open(f"img{i}.jpg")) for i in range(10)]-images = torch.stack(images).to(device)--with torch.no_grad():- image_features = model.encode_image(images)- image_features /= image_features.norm(dim=-1, keepdim=True)--# Batch text-texts = ["a dog", "a cat", "a bird"]-text_tokens = clip.tokenize(texts).to(device)--with torch.no_grad():- text_features = model.encode_text(text_tokens)- text_features /= text_features.norm(dim=-1, keepdim=True)--# Similarity matrix (10 images × 3 texts)-similarities = image_features @ text_features.T-print(similarities.shape) # (10, 3)-```--## 与向量数据库集成--```python-# Store CLIP embeddings in Chroma/FAISS-import chromadb--client = chromadb.Client()-collection = client.create_collection("image_embeddings")--# Add image embeddings-for img_path, embedding in zip(image_paths, image_embeddings):- collection.add(- embeddings=[embedding.cpu().numpy().tolist()],- metadatas=[{"path": img_path}],- ids=[img_path]- )--# Query with text-query = "a sunset"-text_embedding = model.encode_text(clip.tokenize([query]))-results = collection.query(- query_embeddings=[text_embedding.cpu().numpy().tolist()],- n_results=5-)-```--## 最佳实践--1. **大多数场景使用 ViT-B/32** — 性能与速度均衡-2. **归一化 embedding(嵌入向量)** — 余弦相似度计算必须归一化-3. **批量处理** — 效率更高-4. **缓存 embedding** — 重新计算代价较高-5. **使用描述性标签** — 零样本性能更好-6. **推荐使用 GPU** — 速度提升 10–50 倍-7. **预处理图像** — 使用提供的 preprocess 函数--## 性能--| 操作 | CPU | GPU (V100) |-|-----------|-----|------------|-| 图像编码 | ~200ms | ~20ms |-| 文本编码 | ~50ms | ~5ms |-| 相似度计算 | <1ms | <1ms |--## 局限性--1. **不适合细粒度任务** — 最适合宽泛类别-2. **需要描述性文本** — 模糊标签效果差-3. **网络数据偏差** — 可能存在数据集偏差-4. **无边界框** — 仅处理整张图像-5. **空间理解有限** — 位置/计数能力较弱--## 资源--- **GitHub**: https://github.com/openai/CLIP ⭐ 25,300+-- **论文**: https://arxiv.org/abs/2103.00020-- **Colab**: https://colab.research.google.com/github/openai/clip/-- **许可证**: MIT\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-guidance.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-guidance.mddeleted file mode 100644index 31407e8dc08..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-guidance.md+++ /dev/null@@ -1,591 +0,0 @@-----title: "Guidance"-sidebar_label: "Guidance"-description: "使用正则表达式和语法控制 LLM 输出,保证生成有效的 JSON/XML/代码,强制结构化格式,并使用 Guidance(微软研究院的约束生成框架)构建多步骤工作流..."------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Guidance--使用正则表达式和语法控制 LLM 输出,保证生成有效的 JSON/XML/代码,强制结构化格式,并使用 Guidance(微软研究院的约束生成框架)构建多步骤工作流--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/guidance` 安装 |-| 路径 | `optional-skills/mlops/guidance` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `guidance`, `transformers` |-| 平台 | linux, macos, windows |-| 标签 | `Prompt Engineering`, `Guidance`, `Constrained Generation`, `Structured Output`, `JSON Validation`, `Grammar`, `Microsoft Research`, `Format Enforcement`, `Multi-Step Workflows` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。-:::--# Guidance:约束 LLM 生成--## 何时使用此 Skill--在以下情况下使用 Guidance:-- **使用正则表达式或语法控制 LLM 输出语法**-- **保证生成有效的 JSON/XML/代码**-- **相比传统 prompting(提示词)方式降低延迟**-- **强制结构化格式**(日期、邮箱、ID 等)-- **使用 Python 风格的控制流构建多步骤工作流**-- **通过语法约束防止无效输出**--**GitHub Stars**:18,000+ | **来自**:微软研究院--## 安装--```bash-# 基础安装-pip install guidance--# 指定后端-pip install guidance[transformers] # Hugging Face 模型-pip install guidance[llama_cpp] # llama.cpp 模型-```--## 快速开始--### 基础示例:结构化生成--```python-from guidance import models, gen--# 加载模型(支持 OpenAI、Transformers、llama.cpp)-lm = models.OpenAI("gpt-4")--# 带约束生成-result = lm + "The capital of France is " + gen("capital", max_tokens=5)--print(result["capital"]) # "Paris"-```--### 使用 Anthropic Claude--```python-from guidance import models, gen, system, user, assistant--# 配置 Claude-lm = models.Anthropic("claude-sonnet-4-5-20250929")--# 使用上下文管理器实现对话格式-with system():- lm += "You are a helpful assistant."--with user():- lm += "What is the capital of France?"--with assistant():- lm += gen(max_tokens=20)-```--## 核心概念--### 1. 上下文管理器--Guidance 使用 Python 风格的上下文管理器实现对话式交互。--```python-from guidance import system, user, assistant, gen--lm = models.Anthropic("claude-sonnet-4-5-20250929")--# 系统消息-with system():- lm += "You are a JSON generation expert."--# 用户消息-with user():- lm += "Generate a person object with name and age."--# 助手回复-with assistant():- lm += gen("response", max_tokens=100)--print(lm["response"])-```--**优势:**-- 自然的对话流程-- 清晰的角色分离-- 易于阅读和维护--### 2. 约束生成--Guidance 使用正则表达式或语法确保输出符合指定模式。--#### 正则表达式约束--```python-from guidance import models, gen--lm = models.Anthropic("claude-sonnet-4-5-20250929")--# 约束为有效邮箱格式-lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")--# 约束为日期格式(YYYY-MM-DD)-lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}")--# 约束为电话号码-lm += "Phone: " + gen("phone", regex=r"\d{3}-\d{3}-\d{4}")--print(lm["email"]) # 保证为有效邮箱-print(lm["date"]) # 保证为 YYYY-MM-DD 格式-```--**工作原理:**-- 正则表达式在 token(词元)级别转换为语法-- 生成过程中过滤无效 token-- 模型只能生成符合匹配条件的输出--#### 选择约束--```python-from guidance import models, gen, select--lm = models.Anthropic("claude-sonnet-4-5-20250929")--# 约束为特定选项-lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")--# 多选题选择-lm += "Best answer: " + select(- ["A) Paris", "B) London", "C) Berlin", "D) Madrid"],- name="answer"-)--print(lm["sentiment"]) # 其中之一:positive、negative、neutral-print(lm["answer"]) # 其中之一:A、B、C 或 D-```--### 3. Token 修复(Token Healing)--Guidance 自动"修复" prompt 与生成内容之间的 token 边界。--**问题:** 分词会产生不自然的边界。--```python-# 不使用 token 修复-prompt = "The capital of France is "-# 最后一个 token:" is "-# 第一个生成的 token 可能是 " Par"(带前导空格)-# 结果:"The capital of France is Paris"(双空格!)-```--**解决方案:** Guidance 回退一个 token 并重新生成。--```python-from guidance import models, gen--lm = models.Anthropic("claude-sonnet-4-5-20250929")--# 默认启用 token 修复-lm += "The capital of France is " + gen("capital", max_tokens=5)-# 结果:"The capital of France is Paris"(间距正确)-```--**优势:**-- 自然的文本边界-- 无尴尬的间距问题-- 更好的模型性能(模型看到自然的 token 序列)--### 4. 基于语法的生成--使用上下文无关语法定义复杂结构。--```python-from guidance import models, gen--lm = models.Anthropic("claude-sonnet-4-5-20250929")--# JSON 语法(简化版)-json_grammar = """-{- "name": <gen name regex="[A-Za-z ]+" max_tokens=20>,- "age": <gen age regex="[0-9]+" max_tokens=3>,- "email": <gen email regex="[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" max_tokens=50>-}-"""--# 生成有效 JSON-lm += gen("person", grammar=json_grammar)--print(lm["person"]) # 保证为有效 JSON 结构-```--**使用场景:**-- 复杂结构化输出-- 嵌套数据结构-- 编程语言语法-- 领域特定语言--### 5. Guidance 函数--使用 `@guidance` 装饰器创建可复用的生成模式。--```python-from guidance import guidance, gen, models--@guidance-def generate_person(lm):- """生成包含姓名和年龄的人物信息。"""- lm += "Name: " + gen("name", max_tokens=20, stop="\n")- lm += "\nAge: " + gen("age", regex=r"[0-9]+", max_tokens=3)- return lm--# 使用该函数-lm = models.Anthropic("claude-sonnet-4-5-20250929")-lm = generate_person(lm)--print(lm["name"])-print(lm["age"])-```--**有状态函数:**--```python-@guidance(stateless=False)-def react_agent(lm, question, tools, max_rounds=5):- """带工具调用的 ReAct agent。"""- lm += f"Question: {question}\n\n"-- for i in range(max_rounds):- # 思考- lm += f"Thought {i+1}: " + gen("thought", stop="\n")-- # 动作- lm += "\nAction: " + select(list(tools.keys()), name="action")-- # 执行工具- tool_result = tools[lm["action"]]()- lm += f"\nObservation: {tool_result}\n\n"-- # 检查是否完成- lm += "Done? " + select(["Yes", "No"], name="done")- if lm["done"] == "Yes":- break-- # 最终答案- lm += "\nFinal Answer: " + gen("answer", max_tokens=100)- return lm-```--## 后端配置--### Anthropic Claude--```python-from guidance import models--lm = models.Anthropic(- model="claude-sonnet-4-5-20250929",- api_key="your-api-key" # 或设置 ANTHROPIC_API_KEY 环境变量-)-```--### OpenAI--```python-lm = models.OpenAI(- model="gpt-4o-mini",- api_key="your-api-key" # 或设置 OPENAI_API_KEY 环境变量-)-```--### 本地模型(Transformers)--```python-from guidance.models import Transformers--lm = Transformers(- "microsoft/Phi-4-mini-instruct",- device="cuda" # 或 "cpu"-)-```--### 本地模型(llama.cpp)--```python-from guidance.models import LlamaCpp--lm = LlamaCpp(- model_path="/path/to/model.gguf",- n_ctx=4096,- n_gpu_layers=35-)-```--## 常用模式--### 模式 1:JSON 生成--```python-from guidance import models, gen, system, user, assistant--lm = models.Anthropic("claude-sonnet-4-5-20250929")--with system():- lm += "You generate valid JSON."--with user():- lm += "Generate a user profile with name, age, and email."--with assistant():- lm += """{- "name": """ + gen("name", regex=r'"[A-Za-z ]+"', max_tokens=30) + """,- "age": """ + gen("age", regex=r"[0-9]+", max_tokens=3) + """,- "email": """ + gen("email", regex=r'"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"', max_tokens=50) + """-}"""--print(lm) # 保证为有效 JSON-```--### 模式 2:分类--```python-from guidance import models, gen, select--lm = models.Anthropic("claude-sonnet-4-5-20250929")--text = "This product is amazing! I love it."--lm += f"Text: {text}\n"-lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")-lm += "\nConfidence: " + gen("confidence", regex=r"[0-9]+", max_tokens=3) + "%"--print(f"Sentiment: {lm['sentiment']}")-print(f"Confidence: {lm['confidence']}%")-```--### 模式 3:多步骤推理--```python-from guidance import models, gen, guidance--@guidance-def chain_of_thought(lm, question):- """逐步推理生成答案。"""- lm += f"Question: {question}\n\n"-- # 生成多个推理步骤- for i in range(3):- lm += f"Step {i+1}: " + gen(f"step_{i+1}", stop="\n", max_tokens=100) + "\n"-- # 最终答案- lm += "\nTherefore, the answer is: " + gen("answer", max_tokens=50)-- return lm--lm = models.Anthropic("claude-sonnet-4-5-20250929")-lm = chain_of_thought(lm, "What is 15% of 200?")--print(lm["answer"])-```--### 模式 4:ReAct Agent--```python-from guidance import models, gen, select, guidance--@guidance(stateless=False)-def react_agent(lm, question):- """带工具调用的 ReAct agent。"""- tools = {- "calculator": lambda expr: eval(expr),- "search": lambda query: f"Search results for: {query}",- }-- lm += f"Question: {question}\n\n"-- for round in range(5):- # 思考- lm += f"Thought: " + gen("thought", stop="\n") + "\n"-- # 动作选择- lm += "Action: " + select(["calculator", "search", "answer"], name="action")-- if lm["action"] == "answer":- lm += "\nFinal Answer: " + gen("answer", max_tokens=100)- break-- # 动作输入- lm += "\nAction Input: " + gen("action_input", stop="\n") + "\n"-- # 执行工具- if lm["action"] in tools:- result = tools[lm["action"]](lm["action_input"])- lm += f"Observation: {result}\n\n"-- return lm--lm = models.Anthropic("claude-sonnet-4-5-20250929")-lm = react_agent(lm, "What is 25 * 4 + 10?")-print(lm["answer"])-```--### 模式 5:数据提取--```python-from guidance import models, gen, guidance--@guidance-def extract_entities(lm, text):- """从文本中提取结构化实体。"""- lm += f"Text: {text}\n\n"-- # 提取人物- lm += "Person: " + gen("person", stop="\n", max_tokens=30) + "\n"-- # 提取组织- lm += "Organization: " + gen("organization", stop="\n", max_tokens=30) + "\n"-- # 提取日期- lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}", max_tokens=10) + "\n"-- # 提取地点- lm += "Location: " + gen("location", stop="\n", max_tokens=30) + "\n"-- return lm--text = "Tim Cook announced at Apple Park on 2024-09-15 in Cupertino."--lm = models.Anthropic("claude-sonnet-4-5-20250929")-lm = extract_entities(lm, text)--print(f"Person: {lm['person']}")-print(f"Organization: {lm['organization']}")-print(f"Date: {lm['date']}")-print(f"Location: {lm['location']}")-```--## 最佳实践--### 1. 使用正则表达式进行格式验证--```python-# ✅ 好:正则表达式确保格式有效-lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")--# ❌ 差:自由生成可能产生无效邮箱-lm += "Email: " + gen("email", max_tokens=50)-```--### 2. 对固定类别使用 select()--```python-# ✅ 好:保证为有效类别-lm += "Status: " + select(["pending", "approved", "rejected"], name="status")--# ❌ 差:可能生成拼写错误或无效值-lm += "Status: " + gen("status", max_tokens=20)-```--### 3. 利用 Token 修复--```python-# 默认启用 token 修复-# 无需特殊操作——自然拼接即可-lm += "The capital is " + gen("capital") # 自动修复-```--### 4. 使用停止序列--```python-# ✅ 好:在换行处停止,适用于单行输出-lm += "Name: " + gen("name", stop="\n")--# ❌ 差:可能生成多行内容-lm += "Name: " + gen("name", max_tokens=50)-```--### 5. 创建可复用函数--```python-# ✅ 好:可复用模式-@guidance-def generate_person(lm):- lm += "Name: " + gen("name", stop="\n")- lm += "\nAge: " + gen("age", regex=r"[0-9]+")- return lm--# 多次使用-lm = generate_person(lm)-lm += "\n\n"-lm = generate_person(lm)-```--### 6. 平衡约束力度--```python-# ✅ 好:合理的约束-lm += gen("name", regex=r"[A-Za-z ]+", max_tokens=30)--# ❌ 过于严格:可能失败或非常缓慢-lm += gen("name", regex=r"^(John|Jane)$", max_tokens=10)-```--## 与替代方案的对比--| 特性 | Guidance | Instructor | Outlines | LMQL |-|---------|----------|------------|----------|------|-| 正则表达式约束 | ✅ 支持 | ❌ 不支持 | ✅ 支持 | ✅ 支持 |-| 语法支持 | ✅ CFG | ❌ 不支持 | ✅ CFG | ✅ CFG |-| Pydantic 验证 | ❌ 不支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 |-| Token 修复 | ✅ 支持 | ❌ 不支持 | ✅ 支持 | ❌ 不支持 |-| 本地模型 | ✅ 支持 | ⚠️ 有限 | ✅ 支持 | ✅ 支持 |-| API 模型 | ✅ 支持 | ✅ 支持 | ⚠️ 有限 | ✅ 支持 |-| Python 风格语法 | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 类 SQL |-| 学习曲线 | 低 | 低 | 中 | 高 |--**何时选择 Guidance:**-- 需要正则表达式/语法约束-- 需要 token 修复-- 构建带控制流的复杂工作流-- 使用本地模型(Transformers、llama.cpp)-- 偏好 Python 风格语法--**何时选择替代方案:**-- Instructor:需要带自动重试的 Pydantic 验证-- Outlines:需要 JSON schema 验证-- LMQL:偏好声明式查询语法--## 性能特性--**延迟降低:**-- 对于约束输出,比传统 prompting 快 30–50%-- Token 修复减少不必要的重新生成-- 语法约束防止无效 token 的生成--**内存占用:**-- 相比无约束生成,额外开销极小-- 语法编译结果在首次使用后缓存-- 推理时高效过滤 token--**Token 效率:**-- 防止在无效输出上浪费 token-- 无需重试循环-- 直接生成有效输出--## 资源--- **文档**:https://guidance.readthedocs.io-- **GitHub**:https://github.com/guidance-ai/guidance(18k+ stars)-- **Notebooks**:https://github.com/guidance-ai/guidance/tree/main/notebooks-- **Discord**:提供社区支持--## 另请参阅--- `references/constraints.md` — 全面的正则表达式和语法模式-- `references/backends.md` — 后端专项配置-- `references/examples.md` — 生产就绪示例\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.mddeleted file mode 100644index 35e9679ab94..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md+++ /dev/null@@ -1,535 +0,0 @@-----title: "Huggingface Tokenizers — 为研究和生产优化的快速 tokenizer"-sidebar_label: "Huggingface Tokenizers"-description: "为研究和生产优化的快速 tokenizer"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Huggingface Tokenizers--为研究和生产优化的快速 tokenizer(分词器)。基于 Rust 的实现可在 <20 秒内对 1GB 文本完成分词。支持 BPE、WordPiece 和 Unigram 算法。可训练自定义词表、追踪对齐关系、处理 padding(填充)/truncation(截断)。与 transformers 无缝集成。当需要高性能分词或训练自定义 tokenizer 时使用。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/huggingface-tokenizers` 安装 |-| 路径 | `optional-skills/mlops/huggingface-tokenizers` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖 | `tokenizers`, `transformers`, `datasets` |-| 平台 | linux, macos, windows |-| 标签 | `Tokenization`, `HuggingFace`, `BPE`, `WordPiece`, `Unigram`, `Fast Tokenization`, `Rust`, `Custom Tokenizer`, `Alignment Tracking`, `Production` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# HuggingFace Tokenizers — 高性能 NLP 分词--具备 Rust 性能与 Python 易用性的快速、生产就绪 tokenizer。--## 何时使用 HuggingFace Tokenizers--**在以下情况下使用 HuggingFace Tokenizers:**-- 需要极快的分词速度(每 GB 文本 <20 秒)-- 从头训练自定义 tokenizer-- 需要对齐追踪(token → 原始文本位置)-- 构建生产级 NLP 流水线-- 需要高效地对大型语料库进行分词--**性能**:-- **速度**:CPU 上对 1GB 文本分词 <20 秒-- **实现**:Rust 核心,提供 Python/Node.js 绑定-- **效率**:比纯 Python 实现快 10–100 倍--**改用其他方案的情况**:-- **SentencePiece**:语言无关,被 T5/ALBERT 使用-- **tiktoken**:OpenAI 用于 GPT 模型的 BPE tokenizer-- **transformers AutoTokenizer**:仅加载预训练模型时使用(内部使用本库)--## 快速开始--### 安装--```bash-# 安装 tokenizers-pip install tokenizers--# 与 transformers 集成-pip install tokenizers transformers-```--### 加载预训练 tokenizer--```python-from tokenizers import Tokenizer--# 从 HuggingFace Hub 加载-tokenizer = Tokenizer.from_pretrained("bert-base-uncased")--# 对文本编码-output = tokenizer.encode("Hello, how are you?")-print(output.tokens) # ['hello', ',', 'how', 'are', 'you', '?']-print(output.ids) # [7592, 1010, 2129, 2024, 2017, 1029]--# 解码还原-text = tokenizer.decode(output.ids)-print(text) # "hello, how are you?"-```--### 训练自定义 BPE tokenizer--```python-from tokenizers import Tokenizer-from tokenizers.models import BPE-from tokenizers.trainers import BpeTrainer-from tokenizers.pre_tokenizers import Whitespace--# 使用 BPE 模型初始化 tokenizer-tokenizer = Tokenizer(BPE(unk_token="[UNK]"))-tokenizer.pre_tokenizer = Whitespace()--# 配置训练器-trainer = BpeTrainer(- vocab_size=30000,- special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],- min_frequency=2-)--# 在文件上训练-files = ["train.txt", "validation.txt"]-tokenizer.train(files, trainer)--# 保存-tokenizer.save("my-tokenizer.json")-```--**训练时间**:100MB 语料约 1–2 分钟,1GB 语料约 10–20 分钟--### 批量编码与 padding--```python-# 启用 padding-tokenizer.enable_padding(pad_id=3, pad_token="[PAD]")--# 批量编码-texts = ["Hello world", "This is a longer sentence"]-encodings = tokenizer.encode_batch(texts)--for encoding in encodings:- print(encoding.ids)-# [101, 7592, 2088, 102, 3, 3, 3]-# [101, 2023, 2003, 1037, 2936, 6251, 102]-```--## 分词算法--### BPE(字节对编码)--**工作原理**:-1. 从字符级词表开始-2. 找出最频繁的字符对-3. 合并为新 token,加入词表-4. 重复直到达到词表大小--**使用者**:GPT-2、GPT-3、RoBERTa、BART、DeBERTa--```python-from tokenizers import Tokenizer-from tokenizers.models import BPE-from tokenizers.trainers import BpeTrainer-from tokenizers.pre_tokenizers import ByteLevel--tokenizer = Tokenizer(BPE(unk_token="<|endoftext|>"))-tokenizer.pre_tokenizer = ByteLevel()--trainer = BpeTrainer(- vocab_size=50257,- special_tokens=["<|endoftext|>"],- min_frequency=2-)--tokenizer.train(files=["data.txt"], trainer=trainer)-```--**优点**:-- 能较好地处理 OOV 词(拆分为子词)-- 词表大小灵活-- 适合形态丰富的语言--**权衡**:-- 分词结果依赖合并顺序-- 可能意外拆分常见词--### WordPiece--**工作原理**:-1. 从字符词表开始-2. 对合并对打分:`frequency(pair) / (frequency(first) × frequency(second))`-3. 合并得分最高的对-4. 重复直到达到词表大小--**使用者**:BERT、DistilBERT、MobileBERT--```python-from tokenizers import Tokenizer-from tokenizers.models import WordPiece-from tokenizers.trainers import WordPieceTrainer-from tokenizers.pre_tokenizers import Whitespace-from tokenizers.normalizers import BertNormalizer--tokenizer = Tokenizer(WordPiece(unk_token="[UNK]"))-tokenizer.normalizer = BertNormalizer(lowercase=True)-tokenizer.pre_tokenizer = Whitespace()--trainer = WordPieceTrainer(- vocab_size=30522,- special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],- continuing_subword_prefix="##"-)--tokenizer.train(files=["corpus.txt"], trainer=trainer)-```--**优点**:-- 优先进行有意义的合并(高分 = 语义相关)-- 在 BERT 中取得了最优结果--**权衡**:-- 若无子词匹配,未知词变为 `[UNK]`-- 保存词表而非合并规则(文件较大)--### Unigram--**工作原理**:-1. 从大词表(所有子串)开始-2. 用当前词表计算语料损失-3. 移除对损失影响最小的 token-4. 重复直到达到词表大小--**使用者**:ALBERT、T5、mBART、XLNet(通过 SentencePiece)--```python-from tokenizers import Tokenizer-from tokenizers.models import Unigram-from tokenizers.trainers import UnigramTrainer--tokenizer = Tokenizer(Unigram())--trainer = UnigramTrainer(- vocab_size=8000,- special_tokens=["<unk>", "<s>", "</s>"],- unk_token="<unk>"-)--tokenizer.train(files=["data.txt"], trainer=trainer)-```--**优点**:-- 概率化(找到最可能的分词方式)-- 适合无词边界的语言-- 能处理多样的语言学上下文--**权衡**:-- 训练计算开销较大-- 需要调整的超参数更多--## 分词流水线--完整流水线:**归一化 → 预分词 → 模型 → 后处理**--### 归一化(Normalization)--清洗并标准化文本:--```python-from tokenizers.normalizers import NFD, StripAccents, Lowercase, Sequence--tokenizer.normalizer = Sequence([- NFD(), # Unicode 归一化(分解)- Lowercase(), # 转为小写- StripAccents() # 去除重音符号-])--# 输入:"Héllo WORLD"-# 归一化后:"hello world"-```--**常用归一化器**:-- `NFD`, `NFC`, `NFKD`, `NFKC` — Unicode 归一化形式-- `Lowercase()` — 转为小写-- `StripAccents()` — 去除重音(é → e)-- `Strip()` — 去除空白-- `Replace(pattern, content)` — 正则替换--### 预分词(Pre-tokenization)--将文本拆分为类词单元:--```python-from tokenizers.pre_tokenizers import Whitespace, Punctuation, Sequence, ByteLevel--# 按空白和标点拆分-tokenizer.pre_tokenizer = Sequence([- Whitespace(),- Punctuation()-])--# 输入:"Hello, world!"-# 预分词后:["Hello", ",", "world", "!"]-```--**常用预分词器**:-- `Whitespace()` — 按空格、制表符、换行符拆分-- `ByteLevel()` — GPT-2 风格的字节级拆分-- `Punctuation()` — 隔离标点-- `Digits(individual_digits=True)` — 逐个拆分数字-- `Metaspace()` — 将空格替换为 ▁(SentencePiece 风格)--### 后处理(Post-processing)--为模型输入添加特殊 token:--```python-from tokenizers.processors import TemplateProcessing--# BERT 风格:[CLS] sentence [SEP]-tokenizer.post_processor = TemplateProcessing(- single="[CLS] $A [SEP]",- pair="[CLS] $A [SEP] $B [SEP]",- special_tokens=[- ("[CLS]", 1),- ("[SEP]", 2),- ],-)-```--**常见模式**:-```python-# GPT-2:sentence <|endoftext|>-TemplateProcessing(- single="$A <|endoftext|>",- special_tokens=[("<|endoftext|>", 50256)]-)--# RoBERTa:<s> sentence </s>-TemplateProcessing(- single="<s> $A </s>",- pair="<s> $A </s> </s> $B </s>",- special_tokens=[("<s>", 0), ("</s>", 2)]-)-```--## 对齐追踪--追踪 token 在原始文本中的位置:--```python-output = tokenizer.encode("Hello, world!")--# 获取 token 偏移量-for token, offset in zip(output.tokens, output.offsets):- start, end = offset- print(f"{token:10} → [{start:2}, {end:2}): {text[start:end]!r}")--# 输出:-# hello → [ 0, 5): 'Hello'-# , → [ 5, 6): ','-# world → [ 7, 12): 'world'-# ! → [12, 13): '!'-```--**使用场景**:-- 命名实体识别(将预测结果映射回文本)-- 问答(提取答案片段)-- Token 分类(将标签对齐到原始位置)--## 与 transformers 集成--### 使用 AutoTokenizer 加载--```python-from transformers import AutoTokenizer--# AutoTokenizer 自动使用快速 tokenizer-tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")--# 检查是否使用快速 tokenizer-print(tokenizer.is_fast) # True--# 访问底层 tokenizers.Tokenizer-fast_tokenizer = tokenizer.backend_tokenizer-print(type(fast_tokenizer)) # <class 'tokenizers.Tokenizer'>-```--### 将自定义 tokenizer 转换为 transformers 格式--```python-from tokenizers import Tokenizer-from transformers import PreTrainedTokenizerFast--# 训练自定义 tokenizer-tokenizer = Tokenizer(BPE())-# ... 训练 tokenizer ...-tokenizer.save("my-tokenizer.json")--# 封装为 transformers 格式-transformers_tokenizer = PreTrainedTokenizerFast(- tokenizer_file="my-tokenizer.json",- unk_token="[UNK]",- pad_token="[PAD]",- cls_token="[CLS]",- sep_token="[SEP]",- mask_token="[MASK]"-)--# 像使用任何 transformers tokenizer 一样使用-outputs = transformers_tokenizer(- "Hello world",- padding=True,- truncation=True,- max_length=512,- return_tensors="pt"-)-```--## 常见模式--### 从迭代器训练(大型数据集)--```python-from datasets import load_dataset--# 加载数据集-dataset = load_dataset("wikitext", "wikitext-103-raw-v1", split="train")--# 创建批量迭代器-def batch_iterator(batch_size=1000):- for i in range(0, len(dataset), batch_size):- yield dataset[i:i + batch_size]["text"]--# 训练 tokenizer-tokenizer.train_from_iterator(- batch_iterator(),- trainer=trainer,- length=len(dataset) # 用于进度条-)-```--**性能**:约 10–20 分钟处理 1GB--### 启用 truncation 和 padding--```python-# 启用 truncation-tokenizer.enable_truncation(max_length=512)--# 启用 padding-tokenizer.enable_padding(- pad_id=tokenizer.token_to_id("[PAD]"),- pad_token="[PAD]",- length=512 # 固定长度,或 None 表示批次最大长度-)--# 同时编码-output = tokenizer.encode("This is a long sentence that will be truncated...")-print(len(output.ids)) # 512-```--### 多进程处理--```python-from tokenizers import Tokenizer-from multiprocessing import Pool--# 加载 tokenizer-tokenizer = Tokenizer.from_file("tokenizer.json")--def encode_batch(texts):- return tokenizer.encode_batch(texts)--# 并行处理大型语料库-with Pool(8) as pool:- # 将语料库拆分为块- chunk_size = 1000- chunks = [corpus[i:i+chunk_size] for i in range(0, len(corpus), chunk_size)]-- # 并行编码- results = pool.map(encode_batch, chunks)-```--**加速比**:8 核下约 5–8 倍--## 性能基准--### 训练速度--| 语料大小 | BPE(30k 词表) | WordPiece(30k) | Unigram(8k) |-|----------|----------------|-----------------|--------------|-| 10 MB | 15 秒 | 18 秒 | 25 秒 |-| 100 MB | 1.5 分钟 | 2 分钟 | 4 分钟 |-| 1 GB | 15 分钟 | 20 分钟 | 40 分钟 |--**硬件**:16 核 CPU,在英文 Wikipedia 上测试--### 分词速度--| 实现方式 | 1 GB 语料 | 吞吐量 |-|----------------|-------------|--------------|-| 纯 Python | ~20 分钟 | ~50 MB/分钟 |-| HF Tokenizers | ~15 秒 | ~4 GB/分钟 |-| **加速比** | **80×** | **80×** |--**测试**:英文文本,平均句长 20 词--### 内存占用--| 任务 | 内存 |-|-------------------------|---------|-| 加载 tokenizer | ~10 MB |-| 训练 BPE(30k 词表) | ~200 MB |-| 编码 100 万句 | ~500 MB |--## 支持的模型--可通过 `from_pretrained()` 获取的预训练 tokenizer:--**BERT 系列**:-- `bert-base-uncased`, `bert-large-cased`-- `distilbert-base-uncased`-- `roberta-base`, `roberta-large`--**GPT 系列**:-- `gpt2`, `gpt2-medium`, `gpt2-large`-- `distilgpt2`--**T5 系列**:-- `t5-small`, `t5-base`, `t5-large`-- `google/flan-t5-xxl`--**其他**:-- `facebook/bart-base`, `facebook/mbart-large-cc25`-- `albert-base-v2`, `albert-xlarge-v2`-- `xlm-roberta-base`, `xlm-roberta-large`--浏览全部:https://huggingface.co/models?library=tokenizers--## 参考资料--- **[训练指南](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/training.md)** — 训练自定义 tokenizer、配置训练器、处理大型数据集-- **[算法深度解析](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/algorithms.md)** — BPE、WordPiece、Unigram 详细说明-- **[流水线组件](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/pipeline.md)** — 归一化器、预分词器、后处理器、解码器-- **[Transformers 集成](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/integration.md)** — AutoTokenizer、PreTrainedTokenizerFast、特殊 token--## 资源--- **文档**:https://huggingface.co/docs/tokenizers-- **GitHub**:https://github.com/huggingface/tokenizers ⭐ 9,000+-- **版本**:0.20.0+-- **课程**:https://huggingface.co/learn/nlp-course/chapter6/1-- **论文**:BPE(Sennrich et al., 2016)、WordPiece(Schuster & Nakajima, 2012)\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-inference-outlines.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-inference-outlines.mddeleted file mode 100644index f82abd10644..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-inference-outlines.md+++ /dev/null@@ -1,671 +0,0 @@-----title: "Outlines — Outlines:结构化 JSON/regex/Pydantic LLM 生成"-sidebar_label: "Outlines"-description: "Outlines:结构化 JSON/regex/Pydantic LLM 生成"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Outlines--Outlines:结构化 JSON/regex/Pydantic LLM 生成。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 使用 `hermes skills install official/mlops/outlines` 安装 |-| 路径 | `optional-skills/mlops/inference/outlines` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `outlines`, `transformers`, `vllm`, `pydantic` |-| 平台 | linux, macos, windows |-| 标签 | `Prompt Engineering`, `Outlines`, `Structured Generation`, `JSON Schema`, `Pydantic`, `Local Models`, `Grammar-Based Generation`, `vLLM`, `Transformers`, `Type Safety` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。-:::--# Outlines:结构化文本生成--## 何时使用此 Skill--在以下情况下使用 Outlines:-- **保证有效的 JSON/XML/代码**结构化生成-- **使用 Pydantic 模型**获得类型安全的输出-- **支持本地模型**(Transformers、llama.cpp、vLLM)-- **通过零开销结构化生成最大化推理速度**-- **自动根据 JSON schema 生成**-- **在 grammar(语法)层面控制 token 采样**--**GitHub Stars**:8,000+ | **来自**:dottxt.ai(前身为 .txt)--## 安装--```bash-# 基础安装-pip install outlines--# 安装特定后端-pip install outlines transformers # Hugging Face 模型-pip install outlines llama-cpp-python # llama.cpp-pip install outlines vllm # vLLM 用于高吞吐量-```--## 快速开始--### 基础示例:分类--```python-import outlines-from typing import Literal--# 加载模型-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")--# 带类型约束的生成-prompt = "Sentiment of 'This product is amazing!': "-generator = outlines.generate.choice(model, ["positive", "negative", "neutral"])-sentiment = generator(prompt)--print(sentiment) # "positive"(保证为其中之一)-```--### 使用 Pydantic 模型--```python-from pydantic import BaseModel-import outlines--class User(BaseModel):- name: str- age: int- email: str--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")--# 生成结构化输出-prompt = "Extract user: John Doe, 30 years old, [email protected]"-generator = outlines.generate.json(model, User)-user = generator(prompt)--print(user.name) # "John Doe"-print(user.age) # 30-print(user.email) # "[email protected]"-```--## 核心概念--### 1. 受约束的 Token 采样--Outlines 使用有限状态机(FSM)在 logit 层面约束 token 生成。--**工作原理:**-1. 将 schema(JSON/Pydantic/regex)转换为上下文无关文法(CFG)-2. 将 CFG 转换为有限状态机(FSM)-3. 在生成的每一步过滤无效 token-4. 当只有一个有效 token 时快速前进--**优势:**-- **零开销**:过滤在 token 层面进行-- **速度提升**:通过确定性路径快速前进-- **保证有效性**:无效输出不可能产生--```python-import outlines--# Pydantic 模型 -> JSON schema -> CFG -> FSM-class Person(BaseModel):- name: str- age: int--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")--# 底层流程:-# 1. Person -> JSON schema-# 2. JSON schema -> CFG-# 3. CFG -> FSM-# 4. FSM 在生成过程中过滤 token--generator = outlines.generate.json(model, Person)-result = generator("Generate person: Alice, 25")-```--### 2. 结构化生成器--Outlines 为不同输出类型提供专用生成器。--#### Choice 生成器--```python-# 多项选择-generator = outlines.generate.choice(- model,- ["positive", "negative", "neutral"]-)--sentiment = generator("Review: This is great!")-# 结果:三个选项之一-```--#### JSON 生成器--```python-from pydantic import BaseModel--class Product(BaseModel):- name: str- price: float- in_stock: bool--# 生成符合 schema 的有效 JSON-generator = outlines.generate.json(model, Product)-product = generator("Extract: iPhone 15, $999, available")--# 保证为有效的 Product 实例-print(type(product)) # <class '__main__.Product'>-```--#### Regex 生成器--```python-# 生成匹配 regex 的文本-generator = outlines.generate.regex(- model,- r"[0-9]{3}-[0-9]{3}-[0-9]{4}" # 电话号码模式-)--phone = generator("Generate phone number:")-# 结果:"555-123-4567"(保证匹配模式)-```--#### 整数/浮点数生成器--```python-# 生成特定数值类型-int_generator = outlines.generate.integer(model)-age = int_generator("Person's age:") # 保证为整数--float_generator = outlines.generate.float(model)-price = float_generator("Product price:") # 保证为浮点数-```--### 3. 模型后端--Outlines 支持多种本地及基于 API 的后端。--#### Transformers(Hugging Face)--```python-import outlines--# 从 Hugging Face 加载-model = outlines.models.transformers(- "microsoft/Phi-3-mini-4k-instruct",- device="cuda" # 或 "cpu"-)--# 与任意生成器配合使用-generator = outlines.generate.json(model, YourModel)-```--#### llama.cpp--```python-# 加载 GGUF 模型-model = outlines.models.llamacpp(- "./models/llama-3.1-8b-instruct.Q4_K_M.gguf",- n_gpu_layers=35-)--generator = outlines.generate.json(model, YourModel)-```--#### vLLM(高吞吐量)--```python-# 用于生产部署-model = outlines.models.vllm(- "meta-llama/Llama-3.1-8B-Instruct",- tensor_parallel_size=2 # 多 GPU-)--generator = outlines.generate.json(model, YourModel)-```--#### OpenAI(有限支持)--```python-# 基础 OpenAI 支持-model = outlines.models.openai(- "gpt-4o-mini",- api_key="your-api-key"-)--# 注意:API 模型部分功能受限-generator = outlines.generate.json(model, YourModel)-```--### 4. Pydantic 集成--Outlines 对 Pydantic 提供一流支持,可自动进行 schema 转换。--#### 基础模型--```python-from pydantic import BaseModel, Field--class Article(BaseModel):- title: str = Field(description="Article title")- author: str = Field(description="Author name")- word_count: int = Field(description="Number of words", gt=0)- tags: list[str] = Field(description="List of tags")--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")-generator = outlines.generate.json(model, Article)--article = generator("Generate article about AI")-print(article.title)-print(article.word_count) # 保证 > 0-```--#### 嵌套模型--```python-class Address(BaseModel):- street: str- city: str- country: str--class Person(BaseModel):- name: str- age: int- address: Address # 嵌套模型--generator = outlines.generate.json(model, Person)-person = generator("Generate person in New York")--print(person.address.city) # "New York"-```--#### Enum 与 Literal--```python-from enum import Enum-from typing import Literal--class Status(str, Enum):- PENDING = "pending"- APPROVED = "approved"- REJECTED = "rejected"--class Application(BaseModel):- applicant: str- status: Status # 必须为枚举值之一- priority: Literal["low", "medium", "high"] # 必须为 literal 之一--generator = outlines.generate.json(model, Application)-app = generator("Generate application")--print(app.status) # Status.PENDING(或 APPROVED/REJECTED)-```--## 常见模式--### 模式 1:数据提取--```python-from pydantic import BaseModel-import outlines--class CompanyInfo(BaseModel):- name: str- founded_year: int- industry: str- employees: int--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")-generator = outlines.generate.json(model, CompanyInfo)--text = """-Apple Inc. was founded in 1976 in the technology industry.-The company employs approximately 164,000 people worldwide.-"""--prompt = f"Extract company information:\n{text}\n\nCompany:"-company = generator(prompt)--print(f"Name: {company.name}")-print(f"Founded: {company.founded_year}")-print(f"Industry: {company.industry}")-print(f"Employees: {company.employees}")-```--### 模式 2:分类--```python-from typing import Literal-import outlines--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")--# 二分类-generator = outlines.generate.choice(model, ["spam", "not_spam"])-result = generator("Email: Buy now! 50% off!")--# 多分类-categories = ["technology", "business", "sports", "entertainment"]-category_gen = outlines.generate.choice(model, categories)-category = category_gen("Article: Apple announces new iPhone...")--# 带置信度-class Classification(BaseModel):- label: Literal["positive", "negative", "neutral"]- confidence: float--classifier = outlines.generate.json(model, Classification)-result = classifier("Review: This product is okay, nothing special")-```--### 模式 3:结构化表单--```python-class UserProfile(BaseModel):- full_name: str- age: int- email: str- phone: str- country: str- interests: list[str]--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")-generator = outlines.generate.json(model, UserProfile)--prompt = """-Extract user profile from:-Name: Alice Johnson-Age: 28-Email: [email protected]-Phone: 555-0123-Country: USA-Interests: hiking, photography, cooking-"""--profile = generator(prompt)-print(profile.full_name)-print(profile.interests) # ["hiking", "photography", "cooking"]-```--### 模式 4:多实体提取--```python-class Entity(BaseModel):- name: str- type: Literal["PERSON", "ORGANIZATION", "LOCATION"]--class DocumentEntities(BaseModel):- entities: list[Entity]--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")-generator = outlines.generate.json(model, DocumentEntities)--text = "Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond."-prompt = f"Extract entities from: {text}"--result = generator(prompt)-for entity in result.entities:- print(f"{entity.name} ({entity.type})")-```--### 模式 5:代码生成--```python-class PythonFunction(BaseModel):- function_name: str- parameters: list[str]- docstring: str- body: str--model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")-generator = outlines.generate.json(model, PythonFunction)--prompt = "Generate a Python function to calculate factorial"-func = generator(prompt)--print(f"def {func.function_name}({', '.join(func.parameters)}):")-print(f' """{func.docstring}"""')-print(f" {func.body}")-```--### 模式 6:批量处理--```python-def batch_extract(texts: list[str], schema: type[BaseModel]):- """从多段文本中提取结构化数据。"""- model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")- generator = outlines.generate.json(model, schema)-- results = []- for text in texts:- result = generator(f"Extract from: {text}")- results.append(result)-- return results--class Person(BaseModel):- name: str- age: int--texts = [- "John is 30 years old",- "Alice is 25 years old",- "Bob is 40 years old"-]--people = batch_extract(texts, Person)-for person in people:- print(f"{person.name}: {person.age}")-```--## 后端配置--### Transformers--```python-import outlines--# 基础用法-model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")--# GPU 配置-model = outlines.models.transformers(- "microsoft/Phi-3-mini-4k-instruct",- device="cuda",- model_kwargs={"torch_dtype": "float16"}-)--# 常用模型-model = outlines.models.transformers("meta-llama/Llama-3.1-8B-Instruct")-model = outlines.models.transformers("mistralai/Mistral-7B-Instruct-v0.3")-model = outlines.models.transformers("Qwen/Qwen2.5-7B-Instruct")-```--### llama.cpp--```python-# 加载 GGUF 模型-model = outlines.models.llamacpp(- "./models/llama-3.1-8b.Q4_K_M.gguf",- n_ctx=4096, # 上下文窗口- n_gpu_layers=35, # GPU 层数- n_threads=8 # CPU 线程数-)--# 完全 GPU 卸载-model = outlines.models.llamacpp(- "./models/model.gguf",- n_gpu_layers=-1 # 所有层在 GPU 上-)-```--### vLLM(生产环境)--```python-# 单 GPU-model = outlines.models.vllm("meta-llama/Llama-3.1-8B-Instruct")--# 多 GPU-model = outlines.models.vllm(- "meta-llama/Llama-3.1-70B-Instruct",- tensor_parallel_size=4 # 4 块 GPU-)--# 带量化-model = outlines.models.vllm(- "meta-llama/Llama-3.1-8B-Instruct",- quantization="awq" # 或 "gptq"-)-```--## 最佳实践--### 1. 使用具体类型--```python-# ✅ 好:具体类型-class Product(BaseModel):- name: str- price: float # 非 str- quantity: int # 非 str- in_stock: bool # 非 str--# ❌ 差:全部用字符串-class Product(BaseModel):- name: str- price: str # 应为 float- quantity: str # 应为 int-```--### 2. 添加约束--```python-from pydantic import Field--# ✅ 好:带约束-class User(BaseModel):- name: str = Field(min_length=1, max_length=100)- age: int = Field(ge=0, le=120)- email: str = Field(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")--# ❌ 差:无约束-class User(BaseModel):- name: str- age: int- email: str-```--### 3. 对分类使用 Enum--```python-# ✅ 好:固定集合使用 Enum-class Priority(str, Enum):- LOW = "low"- MEDIUM = "medium"- HIGH = "high"--class Task(BaseModel):- title: str- priority: Priority--# ❌ 差:自由格式字符串-class Task(BaseModel):- title: str- priority: str # 可以是任意值-```--### 4. 在 Prompt 中提供上下文--```python-# ✅ 好:清晰的上下文-prompt = """-Extract product information from the following text.-Text: iPhone 15 Pro costs $999 and is currently in stock.-Product:-"""--# ❌ 差:上下文不足-prompt = "iPhone 15 Pro costs $999 and is currently in stock."-```--### 5. 处理可选字段--```python-from typing import Optional--# ✅ 好:对不完整数据使用可选字段-class Article(BaseModel):- title: str # 必填- author: Optional[str] = None # 可选- date: Optional[str] = None # 可选- tags: list[str] = [] # 默认空列表--# 即使 author/date 缺失也能成功-```--## 与替代方案的对比--| 特性 | Outlines | Instructor | Guidance | LMQL |-|---------|----------|------------|----------|------|-| Pydantic 支持 | ✅ 原生 | ✅ 原生 | ❌ 无 | ❌ 无 |-| JSON Schema | ✅ 支持 | ✅ 支持 | ⚠️ 有限 | ✅ 支持 |-| Regex 约束 | ✅ 支持 | ❌ 无 | ✅ 支持 | ✅ 支持 |-| 本地模型 | ✅ 完整 | ⚠️ 有限 | ✅ 完整 | ✅ 完整 |-| API 模型 | ⚠️ 有限 | ✅ 完整 | ✅ 完整 | ✅ 完整 |-| 零开销 | ✅ 支持 | ❌ 无 | ⚠️ 部分 | ✅ 支持 |-| 自动重试 | ❌ 无 | ✅ 支持 | ❌ 无 | ❌ 无 |-| 学习曲线 | 低 | 低 | 低 | 高 |--**何时选择 Outlines:**-- 使用本地模型(Transformers、llama.cpp、vLLM)-- 需要最大推理速度-- 需要 Pydantic 模型支持-- 需要零开销结构化生成-- 需要控制 token 采样过程--**何时选择替代方案:**-- Instructor:需要 API 模型并支持自动重试-- Guidance:需要 token healing 和复杂工作流-- LMQL:偏好声明式查询语法--## 性能特性--**速度:**-- **零开销**:结构化生成与无约束生成同样快速-- **快速前进优化**:跳过确定性 token-- **比生成后验证方案快 1.2–2 倍**--**内存:**-- FSM 每个 schema 编译一次(已缓存)-- 极低的运行时开销-- 配合 vLLM 可实现高吞吐量--**准确性:**-- **100% 有效输出**(由 FSM 保证)-- 无需重试循环-- 确定性 token 过滤--## 资源--- **文档**:https://outlines-dev.github.io/outlines-- **GitHub**:https://github.com/outlines-dev/outlines(8k+ stars)-- **Discord**:https://discord.gg/R9DSu34mGd-- **博客**:https://blog.dottxt.co--## 另请参阅--- `references/json_generation.md` — 全面的 JSON 与 Pydantic 模式-- `references/backends.md` — 后端专项配置-- `references/examples.md` — 生产就绪示例\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-instructor.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-instructor.mddeleted file mode 100644index 191f75f840a..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-instructor.md+++ /dev/null@@ -1,759 +0,0 @@-----title: "Instructor"-sidebar_label: "Instructor"-description: "使用 Pydantic 验证从 LLM 响应中提取结构化数据,自动重试失败的提取,以类型安全方式解析复杂 JSON,并使用 Instructor 流式传输部分结果——经过实战检验的结构化输出库"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Instructor--使用 Pydantic 验证从 LLM 响应中提取结构化数据,自动重试失败的提取,以类型安全方式解析复杂 JSON,并使用 Instructor 流式传输部分结果——经过实战检验的结构化输出库--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/instructor` 安装 |-| 路径 | `optional-skills/mlops/instructor` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `instructor`, `pydantic`, `openai`, `anthropic` |-| 平台 | linux, macos, windows |-| 标签 | `Prompt Engineering`, `Instructor`, `Structured Output`, `Pydantic`, `Data Extraction`, `JSON Parsing`, `Type Safety`, `Validation`, `Streaming`, `OpenAI`, `Anthropic` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# Instructor:结构化 LLM 输出--## 何时使用此 Skill--在以下情况下使用 Instructor:-- **从 LLM 响应中可靠地提取结构化数据**-- **根据 Pydantic schema 自动验证输出**-- **通过自动错误处理重试失败的提取**-- **以类型安全和验证方式解析复杂 JSON**-- **流式传输部分结果**以进行实时处理-- **以一致的 API 支持多个 LLM 提供商**--**GitHub Stars**:15,000+|**实战检验**:100,000+ 开发者--## 安装--```bash-# 基础安装-pip install instructor--# 指定提供商-pip install "instructor[anthropic]" # Anthropic Claude-pip install "instructor[openai]" # OpenAI-pip install "instructor[all]" # 所有提供商-```--## 快速开始--### 基础示例:提取用户数据--```python-import instructor-from pydantic import BaseModel-from anthropic import Anthropic--# Define output structure-class User(BaseModel):- name: str- age: int- email: str--# Create instructor client-client = instructor.from_anthropic(Anthropic())--# Extract structured data-user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "John Doe is 30 years old. His email is [email protected]"- }],- response_model=User-)--print(user.name) # "John Doe"-print(user.age) # 30-print(user.email) # "[email protected]"-```--### 使用 OpenAI--```python-from openai import OpenAI--client = instructor.from_openai(OpenAI())--user = client.chat.completions.create(- model="gpt-4o-mini",- response_model=User,- messages=[{"role": "user", "content": "Extract: Alice, 25, [email protected]"}]-)-```--## 核心概念--### 1. 响应模型(Pydantic)--响应模型定义 LLM 输出的结构和验证规则。--#### 基础模型--```python-from pydantic import BaseModel, Field--class Article(BaseModel):- title: str = Field(description="Article title")- author: str = Field(description="Author name")- word_count: int = Field(description="Number of words", gt=0)- tags: list[str] = Field(description="List of relevant tags")--article = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Analyze this article: [article text]"- }],- response_model=Article-)-```--**优势:**-- 使用 Python 类型提示保证类型安全-- 自动验证(word_count > 0)-- 通过 Field 描述实现自文档化-- IDE 自动补全支持--#### 嵌套模型--```python-class Address(BaseModel):- street: str- city: str- country: str--class Person(BaseModel):- name: str- age: int- address: Address # Nested model--person = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "John lives at 123 Main St, Boston, USA"- }],- response_model=Person-)--print(person.address.city) # "Boston"-```--#### 可选字段--```python-from typing import Optional--class Product(BaseModel):- name: str- price: float- discount: Optional[float] = None # Optional- description: str = Field(default="No description") # Default value--# LLM doesn't need to provide discount or description-```--#### 使用枚举约束值--```python-from enum import Enum--class Sentiment(str, Enum):- POSITIVE = "positive"- NEGATIVE = "negative"- NEUTRAL = "neutral"--class Review(BaseModel):- text: str- sentiment: Sentiment # Only these 3 values allowed--review = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "This product is amazing!"- }],- response_model=Review-)--print(review.sentiment) # Sentiment.POSITIVE-```--### 2. 验证--Pydantic 自动验证 LLM 输出。若验证失败,Instructor 会自动重试。--#### 内置验证器--```python-from pydantic import Field, EmailStr, HttpUrl--class Contact(BaseModel):- name: str = Field(min_length=2, max_length=100)- age: int = Field(ge=0, le=120) # 0 <= age <= 120- email: EmailStr # Validates email format- website: HttpUrl # Validates URL format--# If LLM provides invalid data, Instructor retries automatically-```--#### 自定义验证器--```python-from pydantic import field_validator--class Event(BaseModel):- name: str- date: str- attendees: int-- @field_validator('date')- def validate_date(cls, v):- """Ensure date is in YYYY-MM-DD format."""- import re- if not re.match(r'\d{4}-\d{2}-\d{2}', v):- raise ValueError('Date must be YYYY-MM-DD format')- return v-- @field_validator('attendees')- def validate_attendees(cls, v):- """Ensure positive attendees."""- if v < 1:- raise ValueError('Must have at least 1 attendee')- return v-```--#### 模型级验证--```python-from pydantic import model_validator--class DateRange(BaseModel):- start_date: str- end_date: str-- @model_validator(mode='after')- def check_dates(self):- """Ensure end_date is after start_date."""- from datetime import datetime- start = datetime.strptime(self.start_date, '%Y-%m-%d')- end = datetime.strptime(self.end_date, '%Y-%m-%d')-- if end < start:- raise ValueError('end_date must be after start_date')- return self-```--### 3. 自动重试--当验证失败时,Instructor 会自动重试,并将错误反馈提供给 LLM。--```python-# Retries up to 3 times if validation fails-user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Extract user from: John, age unknown"- }],- response_model=User,- max_retries=3 # Default is 3-)--# If age can't be extracted, Instructor tells the LLM:-# "Validation error: age - field required"-# LLM tries again with better extraction-```--**工作原理:**-1. LLM 生成输出-2. Pydantic 进行验证-3. 若无效:将错误信息发回给 LLM-4. LLM 根据错误反馈重新尝试-5. 重复直至达到 max_retries 次数--### 4. 流式传输--流式传输部分结果以进行实时处理。--#### 流式传输部分对象--```python-from instructor import Partial--class Story(BaseModel):- title: str- content: str- tags: list[str]--# Stream partial updates as LLM generates-for partial_story in client.messages.create_partial(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Write a short sci-fi story"- }],- response_model=Story-):- print(f"Title: {partial_story.title}")- print(f"Content so far: {partial_story.content[:100]}...")- # Update UI in real-time-```--#### 流式传输可迭代对象--```python-class Task(BaseModel):- title: str- priority: str--# Stream list items as they're generated-tasks = client.messages.create_iterable(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Generate 10 project tasks"- }],- response_model=Task-)--for task in tasks:- print(f"- {task.title} ({task.priority})")- # Process each task as it arrives-```--## 提供商配置--### Anthropic Claude--```python-import instructor-from anthropic import Anthropic--client = instructor.from_anthropic(- Anthropic(api_key="your-api-key")-)--# Use with Claude models-response = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=YourModel-)-```--### OpenAI--```python-from openai import OpenAI--client = instructor.from_openai(- OpenAI(api_key="your-api-key")-)--response = client.chat.completions.create(- model="gpt-4o-mini",- response_model=YourModel,- messages=[...]-)-```--### 本地模型(Ollama)--```python-from openai import OpenAI--# Point to local Ollama server-client = instructor.from_openai(- OpenAI(- base_url="http://localhost:11434/v1",- api_key="ollama" # Required but ignored- ),- mode=instructor.Mode.JSON-)--response = client.chat.completions.create(- model="llama3.1",- response_model=YourModel,- messages=[...]-)-```--## 常用模式--### 模式 1:从文本中提取数据--```python-class CompanyInfo(BaseModel):- name: str- founded_year: int- industry: str- employees: int- headquarters: str--text = """-Tesla, Inc. was founded in 2003. It operates in the automotive and energy-industry with approximately 140,000 employees. The company is headquartered-in Austin, Texas.-"""--company = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract company information from: {text}"- }],- response_model=CompanyInfo-)-```--### 模式 2:分类--```python-class Category(str, Enum):- TECHNOLOGY = "technology"- FINANCE = "finance"- HEALTHCARE = "healthcare"- EDUCATION = "education"- OTHER = "other"--class ArticleClassification(BaseModel):- category: Category- confidence: float = Field(ge=0.0, le=1.0)- keywords: list[str]--classification = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": "Classify this article: [article text]"- }],- response_model=ArticleClassification-)-```--### 模式 3:多实体提取--```python-class Person(BaseModel):- name: str- role: str--class Organization(BaseModel):- name: str- industry: str--class Entities(BaseModel):- people: list[Person]- organizations: list[Organization]- locations: list[str]--text = "Tim Cook, CEO of Apple, announced at the event in Cupertino..."--entities = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract all entities from: {text}"- }],- response_model=Entities-)--for person in entities.people:- print(f"{person.name} - {person.role}")-```--### 模式 4:结构化分析--```python-class SentimentAnalysis(BaseModel):- overall_sentiment: Sentiment- positive_aspects: list[str]- negative_aspects: list[str]- suggestions: list[str]- score: float = Field(ge=-1.0, le=1.0)--review = "The product works well but setup was confusing..."--analysis = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Analyze this review: {review}"- }],- response_model=SentimentAnalysis-)-```--### 模式 5:批量处理--```python-def extract_person(text: str) -> Person:- return client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[{- "role": "user",- "content": f"Extract person from: {text}"- }],- response_model=Person- )--texts = [- "John Doe is a 30-year-old engineer",- "Jane Smith, 25, works in marketing",- "Bob Johnson, age 40, software developer"-]--people = [extract_person(text) for text in texts]-```--## 高级特性--### 联合类型--```python-from typing import Union--class TextContent(BaseModel):- type: str = "text"- content: str--class ImageContent(BaseModel):- type: str = "image"- url: HttpUrl- caption: str--class Post(BaseModel):- title: str- content: Union[TextContent, ImageContent] # Either type--# LLM chooses appropriate type based on content-```--### 动态模型--```python-from pydantic import create_model--# Create model at runtime-DynamicUser = create_model(- 'User',- name=(str, ...),- age=(int, Field(ge=0)),- email=(EmailStr, ...)-)--user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=DynamicUser-)-```--### 自定义模式--```python-# For providers without native structured outputs-client = instructor.from_anthropic(- Anthropic(),- mode=instructor.Mode.JSON # JSON mode-)--# Available modes:-# - Mode.ANTHROPIC_TOOLS (recommended for Claude)-# - Mode.JSON (fallback)-# - Mode.TOOLS (OpenAI tools)-```--### 上下文管理--```python-# Single-use client-with instructor.from_anthropic(Anthropic()) as client:- result = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=YourModel- )- # Client closed automatically-```--## 错误处理--### 处理验证错误--```python-from pydantic import ValidationError--try:- user = client.messages.create(- model="claude-sonnet-4-5-20250929",- max_tokens=1024,- messages=[...],- response_model=User,- max_retries=3- )-except ValidationError as e:- print(f"Failed after retries: {e}")- # Handle gracefully--except Exception as e:- print(f"API error: {e}")-```--### 自定义错误信息--```python-class ValidatedUser(BaseModel):- name: str = Field(description="Full name, 2-100 characters")- age: int = Field(description="Age between 0 and 120", ge=0, le=120)- email: EmailStr = Field(description="Valid email address")-- class Config:- # Custom error messages- json_schema_extra = {- "examples": [- {- "name": "John Doe",- "age": 30,- "email": "[email protected]"- }- ]- }-```--## 最佳实践--### 1. 清晰的字段描述--```python-# ❌ Bad: Vague-class Product(BaseModel):- name: str- price: float--# ✅ Good: Descriptive-class Product(BaseModel):- name: str = Field(description="Product name from the text")- price: float = Field(description="Price in USD, without currency symbol")-```--### 2. 使用适当的验证--```python-# ✅ Good: Constrain values-class Rating(BaseModel):- score: int = Field(ge=1, le=5, description="Rating from 1 to 5 stars")- review: str = Field(min_length=10, description="Review text, at least 10 chars")-```--### 3. 在 prompt(提示词)中提供示例--```python-messages = [{- "role": "user",- "content": """Extract person info from: "John, 30, engineer"--Example format:-{- "name": "John Doe",- "age": 30,- "occupation": "engineer"-}"""-}]-```--### 4. 对固定类别使用枚举--```python-# ✅ Good: Enum ensures valid values-class Status(str, Enum):- PENDING = "pending"- APPROVED = "approved"- REJECTED = "rejected"--class Application(BaseModel):- status: Status # LLM must choose from enum-```--### 5. 优雅处理缺失数据--```python-class PartialData(BaseModel):- required_field: str- optional_field: Optional[str] = None- default_field: str = "default_value"--# LLM only needs to provide required_field-```--## 与其他方案的对比--| 特性 | Instructor | 手动 JSON | LangChain | DSPy |-|---------|------------|-------------|-----------|------|-| 类型安全 | ✅ 是 | ❌ 否 | ⚠️ 部分 | ✅ 是 |-| 自动验证 | ✅ 是 | ❌ 否 | ❌ 否 | ⚠️ 有限 |-| 自动重试 | ✅ 是 | ❌ 否 | ❌ 否 | ✅ 是 |-| 流式传输 | ✅ 是 | ❌ 否 | ✅ 是 | ❌ 否 |-| 多提供商 | ✅ 是 | ⚠️ 手动 | ✅ 是 | ✅ 是 |-| 学习曲线 | 低 | 低 | 中 | 高 |--**何时选择 Instructor:**-- 需要结构化、经过验证的输出-- 需要类型安全和 IDE 支持-- 需要自动重试-- 构建数据提取系统--**何时选择其他方案:**-- DSPy:需要 prompt 优化-- LangChain:构建复杂链路-- 手动:简单的一次性提取--## 资源--- **文档**:https://python.useinstructor.com-- **GitHub**:https://github.com/jxnl/instructor(15k+ stars)-- **Cookbook**:https://python.useinstructor.com/examples-- **Discord**:提供社区支持--## 另请参阅--- `references/validation.md` — 高级验证模式-- `references/providers.md` — 提供商专项配置-- `references/examples.md` — 真实使用案例\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-llava.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-llava.mddeleted file mode 100644index d3fd7bc1540..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-llava.md+++ /dev/null@@ -1,323 +0,0 @@-----title: "Llava — 大型语言与视觉助手"-sidebar_label: "Llava"-description: "大型语言与视觉助手"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Llava--大型语言与视觉助手。支持视觉指令微调(instruction tuning)和基于图像的对话。将 CLIP 视觉编码器与 Vicuna/LLaMA 语言模型相结合。支持多轮图像对话、视觉问答(VQA)和指令跟随。适用于视觉语言聊天机器人或图像理解任务。最适合对话式图像分析。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/llava` 安装 |-| 路径 | `optional-skills/mlops/llava` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `transformers`, `torch`, `pillow` |-| 平台 | linux, macos, windows |-| 标签 | `LLaVA`, `Vision-Language`, `Multimodal`, `Visual Question Answering`, `Image Chat`, `CLIP`, `Vicuna`, `Conversational AI`, `Instruction Tuning`, `VQA` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# LLaVA - 大型语言与视觉助手--用于对话式图像理解的开源视觉语言模型。--## 何时使用 LLaVA--**适用场景:**-- 构建视觉语言聊天机器人-- 视觉问答(VQA)-- 图像描述与字幕生成-- 多轮图像对话-- 视觉指令跟随-- 含图像的文档理解--**指标**:-- **GitHub 23,000+ 星标**-- GPT-4V 级别能力(目标)-- Apache 2.0 许可证-- 多种模型规格(7B–34B 参数)--**改用其他方案的情况**:-- **GPT-4V**:质量最高,基于 API-- **CLIP**:简单零样本分类-- **BLIP-2**:更适合纯字幕生成-- **Flamingo**:研究用途,非开源--## 快速开始--### 安装--```bash-# Clone repository-git clone https://github.com/haotian-liu/LLaVA-cd LLaVA--# Install-pip install -e .-```--### 基本用法--```python-from llava.model.builder import load_pretrained_model-from llava.mm_utils import get_model_name_from_path, process_images, tokenizer_image_token-from llava.constants import IMAGE_TOKEN_INDEX, DEFAULT_IMAGE_TOKEN-from llava.conversation import conv_templates-from PIL import Image-import torch--# Load model-model_path = "liuhaotian/llava-v1.5-7b"-tokenizer, model, image_processor, context_len = load_pretrained_model(- model_path=model_path,- model_base=None,- model_name=get_model_name_from_path(model_path)-)--# Load image-image = Image.open("image.jpg")-image_tensor = process_images([image], image_processor, model.config)-image_tensor = image_tensor.to(model.device, dtype=torch.float16)--# Create conversation-conv = conv_templates["llava_v1"].copy()-conv.append_message(conv.roles[0], DEFAULT_IMAGE_TOKEN + "\nWhat is in this image?")-conv.append_message(conv.roles[1], None)-prompt = conv.get_prompt()--# Generate response-input_ids = tokenizer_image_token(prompt, tokenizer, IMAGE_TOKEN_INDEX, return_tensors='pt').unsqueeze(0).to(model.device)--with torch.inference_mode():- output_ids = model.generate(- input_ids,- images=image_tensor,- do_sample=True,- temperature=0.2,- max_new_tokens=512- )--response = tokenizer.decode(output_ids[0], skip_special_tokens=True).strip()-print(response)-```--## 可用模型--| 模型 | 参数量 | 显存 | 质量 |-|-------|------------|------|---------|-| LLaVA-v1.5-7B | 7B | ~14 GB | 良好 |-| LLaVA-v1.5-13B | 13B | ~28 GB | 较好 |-| LLaVA-v1.6-34B | 34B | ~70 GB | 最佳 |--```python-# Load different models-model_7b = "liuhaotian/llava-v1.5-7b"-model_13b = "liuhaotian/llava-v1.5-13b"-model_34b = "liuhaotian/llava-v1.6-34b"--# 4-bit quantization for lower VRAM-load_4bit = True # Reduces VRAM by ~4×-```--## CLI 用法--```bash-# Single image query-python -m llava.serve.cli \- --model-path liuhaotian/llava-v1.5-7b \- --image-file image.jpg \- --query "What is in this image?"--# Multi-turn conversation-python -m llava.serve.cli \- --model-path liuhaotian/llava-v1.5-7b \- --image-file image.jpg-# Then type questions interactively-```--## Web UI(Gradio)--```bash-# Launch Gradio interface-python -m llava.serve.gradio_web_server \- --model-path liuhaotian/llava-v1.5-7b \- --load-4bit # Optional: reduce VRAM--# Access at http://localhost:7860-```--## 多轮对话--```python-# Initialize conversation-conv = conv_templates["llava_v1"].copy()--# Turn 1-conv.append_message(conv.roles[0], DEFAULT_IMAGE_TOKEN + "\nWhat is in this image?")-conv.append_message(conv.roles[1], None)-response1 = generate(conv, model, image) # "A dog playing in a park"--# Turn 2-conv.messages[-1][1] = response1 # Add previous response-conv.append_message(conv.roles[0], "What breed is the dog?")-conv.append_message(conv.roles[1], None)-response2 = generate(conv, model, image) # "Golden Retriever"--# Turn 3-conv.messages[-1][1] = response2-conv.append_message(conv.roles[0], "What time of day is it?")-conv.append_message(conv.roles[1], None)-response3 = generate(conv, model, image)-```--## 常见任务--### 图像字幕生成--```python-question = "Describe this image in detail."-response = ask(model, image, question)-```--### 视觉问答--```python-question = "How many people are in the image?"-response = ask(model, image, question)-```--### 目标检测(文本形式)--```python-question = "List all the objects you can see in this image."-response = ask(model, image, question)-```--### 场景理解--```python-question = "What is happening in this scene?"-response = ask(model, image, question)-```--### 文档理解--```python-question = "What is the main topic of this document?"-response = ask(model, document_image, question)-```--## 训练自定义模型--```bash-# Stage 1: Feature alignment (558K image-caption pairs)-bash scripts/v1_5/pretrain.sh--# Stage 2: Visual instruction tuning (150K instruction data)-bash scripts/v1_5/finetune.sh-```--## 量化(降低显存占用)--```python-# 4-bit quantization-tokenizer, model, image_processor, context_len = load_pretrained_model(- model_path="liuhaotian/llava-v1.5-13b",- model_base=None,- model_name=get_model_name_from_path("liuhaotian/llava-v1.5-13b"),- load_4bit=True # Reduces VRAM ~4×-)--# 8-bit quantization-load_8bit=True # Reduces VRAM ~2×-```--## 最佳实践--1. **从 7B 模型开始** — 质量良好,显存需求可控-2. **使用 4-bit 量化** — 显著降低显存占用-3. **需要 GPU** — CPU 推理极慢-4. **清晰的 prompt** — 具体问题能获得更好的答案-5. **多轮对话** — 保持对话上下文-6. **温度 0.2–0.7** — 平衡创造性与一致性-7. **`max_new_tokens` 512–1024** — 用于详细回复-8. **批量处理** — 按顺序处理多张图像--## 性能--| 模型 | 显存(FP16) | 显存(4-bit) | 速度(tokens/s) |-|-------|-------------|--------------|------------------|-| 7B | ~14 GB | ~4 GB | ~20 |-| 13B | ~28 GB | ~8 GB | ~12 |-| 34B | ~70 GB | ~18 GB | ~5 |--*在 A100 GPU 上测试*--## 基准测试--LLaVA 在以下基准上取得了有竞争力的分数:-- **VQAv2**:78.5%-- **GQA**:62.0%-- **MM-Vet**:35.4%-- **MMBench**:64.3%--## 局限性--1. **幻觉** — 可能描述图像中不存在的内容-2. **空间推理** — 难以精确定位位置-3. **小字体文本** — 难以识别细小字体-4. **目标计数** — 对大量目标计数不精确-5. **显存需求** — 需要高性能 GPU-6. **推理速度** — 比 CLIP 慢--## 与框架集成--### LangChain--```python-from langchain.llms.base import LLM--class LLaVALLM(LLM):- def _call(self, prompt, stop=None):- # Custom LLaVA inference- return response--llm = LLaVALLM()-```--### Gradio 应用--```python-import gradio as gr--def chat(image, text, history):- response = ask_llava(model, image, text)- return response--demo = gr.ChatInterface(- chat,- additional_inputs=[gr.Image(type="pil")],- title="LLaVA Chat"-)-demo.launch()-```--## 资源--- **GitHub**:https://github.com/haotian-liu/LLaVA ⭐ 23,000+-- **论文**:https://arxiv.org/abs/2304.08485-- **演示**:https://llava.hliu.cc-- **模型**:https://huggingface.co/liuhaotian-- **许可证**:Apache 2.0\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-pinecone.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-pinecone.mddeleted file mode 100644index ca871f0534f..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-pinecone.md+++ /dev/null@@ -1,377 +0,0 @@-----title: "Pinecone — 面向生产级 AI 应用的托管向量数据库"-sidebar_label: "Pinecone"-description: "面向生产级 AI 应用的托管向量数据库"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Pinecone--面向生产级 AI 应用的托管向量数据库。全托管、自动扩缩容,支持混合搜索(稠密 + 稀疏向量)、元数据过滤和命名空间。低延迟(<100ms p95)。适用于生产级 RAG、推荐系统或大规模语义搜索。最适合 serverless(无服务器)托管基础设施。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/pinecone` 安装 |-| 路径 | `optional-skills/mlops/pinecone` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖 | `pinecone-client` |-| 平台 | linux, macos, windows |-| 标签 | `RAG`, `Pinecone`, `Vector Database`, `Managed Service`, `Serverless`, `Hybrid Search`, `Production`, `Auto-Scaling`, `Low Latency`, `Recommendations` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# Pinecone - 托管向量数据库--面向生产级 AI 应用的向量数据库。--## 何时使用 Pinecone--**适用场景:**-- 需要托管的 serverless 向量数据库-- 生产级 RAG 应用-- 需要自动扩缩容-- 对低延迟有严格要求(<100ms)-- 不想自行管理基础设施-- 需要混合搜索(稠密 + 稀疏向量)--**指标**:-- 全托管 SaaS-- 自动扩缩容至数十亿向量-- **p95 延迟 <100ms**-- 99.9% 正常运行时间 SLA--**改用其他方案的场景**:-- **Chroma**:自托管、开源-- **FAISS**:离线、纯相似度搜索-- **Weaviate**:自托管、功能更丰富--## 快速开始--### 安装--```bash-pip install pinecone-client-```--### 基本用法--```python-from pinecone import Pinecone, ServerlessSpec--# Initialize-pc = Pinecone(api_key="your-api-key")--# Create index-pc.create_index(- name="my-index",- dimension=1536, # Must match embedding dimension- metric="cosine", # or "euclidean", "dotproduct"- spec=ServerlessSpec(cloud="aws", region="us-east-1")-)--# Connect to index-index = pc.Index("my-index")--# Upsert vectors-index.upsert(vectors=[- {"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "A"}},- {"id": "vec2", "values": [0.3, 0.4, ...], "metadata": {"category": "B"}}-])--# Query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- include_metadata=True-)--print(results["matches"])-```--## 核心操作--### 创建索引--```python-# Serverless (recommended)-pc.create_index(- name="my-index",- dimension=1536,- metric="cosine",- spec=ServerlessSpec(- cloud="aws", # or "gcp", "azure"- region="us-east-1"- )-)--# Pod-based (for consistent performance)-from pinecone import PodSpec--pc.create_index(- name="my-index",- dimension=1536,- metric="cosine",- spec=PodSpec(- environment="us-east1-gcp",- pod_type="p1.x1"- )-)-```--### 插入向量(Upsert)--```python-# Single upsert-index.upsert(vectors=[- {- "id": "doc1",- "values": [0.1, 0.2, ...], # 1536 dimensions- "metadata": {- "text": "Document content",- "category": "tutorial",- "timestamp": "2025-01-01"- }- }-])--# Batch upsert (recommended)-vectors = [- {"id": f"vec{i}", "values": embedding, "metadata": metadata}- for i, (embedding, metadata) in enumerate(zip(embeddings, metadatas))-]--index.upsert(vectors=vectors, batch_size=100)-```--### 查询向量--```python-# Basic query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=10,- include_metadata=True,- include_values=False-)--# With metadata filtering-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- filter={"category": {"$eq": "tutorial"}}-)--# Namespace query-results = index.query(- vector=[0.1, 0.2, ...],- top_k=5,- namespace="production"-)--# Access results-for match in results["matches"]:- print(f"ID: {match['id']}")- print(f"Score: {match['score']}")- print(f"Metadata: {match['metadata']}")-```--### 元数据过滤--```python-# Exact match-filter = {"category": "tutorial"}--# Comparison-filter = {"price": {"$gte": 100}} # $gt, $gte, $lt, $lte, $ne--# Logical operators-filter = {- "$and": [- {"category": "tutorial"},- {"difficulty": {"$lte": 3}}- ]-} # Also: $or--# In operator-filter = {"tags": {"$in": ["python", "ml"]}}-```--## 命名空间--```python-# Partition data by namespace-index.upsert(- vectors=[{"id": "vec1", "values": [...]}],- namespace="user-123"-)--# Query specific namespace-results = index.query(- vector=[...],- namespace="user-123",- top_k=5-)--# List namespaces-stats = index.describe_index_stats()-print(stats['namespaces'])-```--## 混合搜索(稠密 + 稀疏向量)--```python-# Upsert with sparse vectors-index.upsert(vectors=[- {- "id": "doc1",- "values": [0.1, 0.2, ...], # Dense vector- "sparse_values": {- "indices": [10, 45, 123], # Token IDs- "values": [0.5, 0.3, 0.8] # TF-IDF scores- },- "metadata": {"text": "..."}- }-])--# Hybrid query-results = index.query(- vector=[0.1, 0.2, ...],- sparse_vector={- "indices": [10, 45],- "values": [0.5, 0.3]- },- top_k=5,- alpha=0.5 # 0=sparse, 1=dense, 0.5=hybrid-)-```--## LangChain 集成--```python-from langchain_pinecone import PineconeVectorStore-from langchain_openai import OpenAIEmbeddings--# Create vector store-vectorstore = PineconeVectorStore.from_documents(- documents=docs,- embedding=OpenAIEmbeddings(),- index_name="my-index"-)--# Query-results = vectorstore.similarity_search("query", k=5)--# With metadata filter-results = vectorstore.similarity_search(- "query",- k=5,- filter={"category": "tutorial"}-)--# As retriever-retriever = vectorstore.as_retriever(search_kwargs={"k": 10})-```--## LlamaIndex 集成--```python-from llama_index.vector_stores.pinecone import PineconeVectorStore--# Connect to Pinecone-pc = Pinecone(api_key="your-key")-pinecone_index = pc.Index("my-index")--# Create vector store-vector_store = PineconeVectorStore(pinecone_index=pinecone_index)--# Use in LlamaIndex-from llama_index.core import StorageContext, VectorStoreIndex--storage_context = StorageContext.from_defaults(vector_store=vector_store)-index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)-```--## 索引管理--```python-# List indices-indexes = pc.list_indexes()--# Describe index-index_info = pc.describe_index("my-index")-print(index_info)--# Get index stats-stats = index.describe_index_stats()-print(f"Total vectors: {stats['total_vector_count']}")-print(f"Namespaces: {stats['namespaces']}")--# Delete index-pc.delete_index("my-index")-```--## 删除向量--```python-# Delete by ID-index.delete(ids=["vec1", "vec2"])--# Delete by filter-index.delete(filter={"category": "old"})--# Delete all in namespace-index.delete(delete_all=True, namespace="test")--# Delete entire index-index.delete(delete_all=True)-```--## 最佳实践--1. **使用 serverless** — 自动扩缩容,成本效益高-2. **批量 upsert** — 效率更高(每批 100-200 条)-3. **添加元数据** — 启用过滤功能-4. **使用命名空间** — 按用户/租户隔离数据-5. **监控用量** — 查看 Pinecone 控制台-6. **优化过滤器** — 对频繁过滤的字段建立索引-7. **用免费套餐测试** — 1 个索引,10 万向量免费-8. **使用混合搜索** — 质量更优-9. **设置合适的维度** — 与 embedding 模型匹配-10. **定期备份** — 导出重要数据--## 性能--| 操作 | 延迟 | 备注 |-|-----------|---------|-------|-| Upsert | ~50-100ms | 每批次 |-| 查询(p50) | ~50ms | 取决于索引大小 |-| 查询(p95) | ~100ms | SLA 目标 |-| 元数据过滤 | ~+10-20ms | 额外开销 |--## 定价(截至 2025 年)--**Serverless**:-- 每百万读取单元 $0.096-- 每百万写入单元 $0.06-- 每 GB 存储/月 $0.06--**免费套餐**:-- 1 个 serverless 索引-- 10 万向量(1536 维)-- 非常适合原型开发--## 资源--- **官网**:https://www.pinecone.io-- **文档**:https://docs.pinecone.io-- **控制台**:https://app.pinecone.io-- **定价**:https://www.pinecone.io/pricing\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-qdrant.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-qdrant.mddeleted file mode 100644index 617c8589370..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-qdrant.md+++ /dev/null@@ -1,514 +0,0 @@-----title: "Qdrant Vector Search — 用于 RAG 和语义搜索的高性能向量相似度搜索引擎"-sidebar_label: "Qdrant Vector Search"-description: "用于 RAG 和语义搜索的高性能向量相似度搜索引擎"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Qdrant Vector Search--用于 RAG 和语义搜索的高性能向量相似度搜索引擎。适用于构建需要快速最近邻搜索、带过滤的混合搜索,或基于 Rust 高性能的可扩展向量存储的生产级 RAG 系统。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 使用 `hermes skills install official/mlops/qdrant` 安装 |-| 路径 | `optional-skills/mlops/qdrant` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖 | `qdrant-client>=1.12.0` |-| 平台 | linux, macos, windows |-| 标签 | `RAG`, `Vector Search`, `Qdrant`, `Semantic Search`, `Embeddings`, `Similarity Search`, `HNSW`, `Production`, `Distributed` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。-:::--# Qdrant - 向量相似度搜索引擎--用 Rust 编写的高性能向量数据库,适用于生产级 RAG 和语义搜索。--## 何时使用 Qdrant--**在以下情况下使用 Qdrant:**-- 构建需要低延迟的生产级 RAG 系统-- 需要混合搜索(向量 + 元数据过滤)-- 需要通过分片/副本实现水平扩展-- 希望本地部署并完全掌控数据-- 每条记录需要多向量存储(稠密 + 稀疏)-- 构建实时推荐系统--**核心特性:**-- **Rust 驱动**:内存安全,高性能-- **丰富过滤**:在搜索时按任意 payload 字段过滤-- **多向量**:每个点支持稠密、稀疏、多稠密向量-- **量化**:标量、乘积、二值量化,节省内存-- **分布式**:Raft 共识、分片、副本-- **REST + gRPC**:两套 API 功能完全对等--**以下情况请使用替代方案:**-- **Chroma**:更简单的配置,嵌入式使用场景-- **FAISS**:追求极致原始速度,研究/批处理场景-- **Pinecone**:完全托管,零运维偏好-- **Weaviate**:偏好 GraphQL,内置向量化器--## 快速开始--### 安装--```bash-# Python 客户端-pip install qdrant-client--# Docker(推荐用于开发)-docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant--# Docker 持久化存储-docker run -p 6333:6333 -p 6334:6334 \- -v $(pwd)/qdrant_storage:/qdrant/storage \- qdrant/qdrant-```--### 基本用法--```python-from qdrant_client import QdrantClient-from qdrant_client.models import Distance, VectorParams, PointStruct--# 连接到 Qdrant-client = QdrantClient(host="localhost", port=6333)--# 创建集合-client.create_collection(- collection_name="documents",- vectors_config=VectorParams(size=384, distance=Distance.COSINE)-)--# 插入带 payload 的向量-client.upsert(- collection_name="documents",- points=[- PointStruct(- id=1,- vector=[0.1, 0.2, ...], # 384 维向量- payload={"title": "Doc 1", "category": "tech"}- ),- PointStruct(- id=2,- vector=[0.3, 0.4, ...],- payload={"title": "Doc 2", "category": "science"}- )- ]-)--# 带过滤的搜索-results = client.search(- collection_name="documents",- query_vector=[0.15, 0.25, ...],- query_filter={- "must": [{"key": "category", "match": {"value": "tech"}}]- },- limit=10-)--for point in results:- print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")-```--## 核心概念--### Points(点)— 基本数据单元--```python-from qdrant_client.models import PointStruct--# Point = ID + 向量 + Payload-point = PointStruct(- id=123, # 整数或 UUID 字符串- vector=[0.1, 0.2, 0.3, ...], # 稠密向量- payload={ # 任意 JSON 元数据- "title": "Document title",- "category": "tech",- "timestamp": 1699900000,- "tags": ["python", "ml"]- }-)--# 批量 upsert(推荐)-client.upsert(- collection_name="documents",- points=[point1, point2, point3],- wait=True # 等待索引完成-)-```--### Collections(集合)— 向量容器--```python-from qdrant_client.models import VectorParams, Distance, HnswConfigDiff--# 使用 HNSW 配置创建集合-client.create_collection(- collection_name="documents",- vectors_config=VectorParams(- size=384, # 向量维度- distance=Distance.COSINE # COSINE、EUCLID、DOT、MANHATTAN- ),- hnsw_config=HnswConfigDiff(- m=16, # 每个节点的连接数(默认 16)- ef_construct=100, # 构建时精度(默认 100)- full_scan_threshold=10000 # 低于此值切换为暴力搜索- ),- on_disk_payload=True # 将 payload 存储在磁盘上-)--# 集合信息-info = client.get_collection("documents")-print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")-```--### 距离度量--| 度量 | 使用场景 | 范围 |-|--------|----------|-------|-| `COSINE` | 文本 embedding、归一化向量 | 0 到 2 |-| `EUCLID` | 空间数据、图像特征 | 0 到 ∞ |-| `DOT` | 推荐系统、非归一化向量 | -∞ 到 ∞ |-| `MANHATTAN` | 稀疏特征、离散数据 | 0 到 ∞ |--## 搜索操作--### 基本搜索--```python-# 简单最近邻搜索-results = client.search(- collection_name="documents",- query_vector=[0.1, 0.2, ...],- limit=10,- with_payload=True,- with_vectors=False # 不返回向量(更快)-)-```--### 带过滤的搜索--```python-from qdrant_client.models import Filter, FieldCondition, MatchValue, Range--# 复杂过滤-results = client.search(- collection_name="documents",- query_vector=query_embedding,- query_filter=Filter(- must=[- FieldCondition(key="category", match=MatchValue(value="tech")),- FieldCondition(key="timestamp", range=Range(gte=1699000000))- ],- must_not=[- FieldCondition(key="status", match=MatchValue(value="archived"))- ]- ),- limit=10-)--# 简写过滤语法-results = client.search(- collection_name="documents",- query_vector=query_embedding,- query_filter={- "must": [- {"key": "category", "match": {"value": "tech"}},- {"key": "price", "range": {"gte": 10, "lte": 100}}- ]- },- limit=10-)-```--### 批量搜索--```python-from qdrant_client.models import SearchRequest--# 单次请求中执行多个查询-results = client.search_batch(- collection_name="documents",- requests=[- SearchRequest(vector=[0.1, ...], limit=5),- SearchRequest(vector=[0.2, ...], limit=5, filter={"must": [...]}),- SearchRequest(vector=[0.3, ...], limit=10)- ]-)-```--## RAG 集成--### 与 sentence-transformers 集成--```python-from sentence_transformers import SentenceTransformer-from qdrant_client import QdrantClient-from qdrant_client.models import VectorParams, Distance, PointStruct--# 初始化-encoder = SentenceTransformer("all-MiniLM-L6-v2")-client = QdrantClient(host="localhost", port=6333)--# 创建集合-client.create_collection(- collection_name="knowledge_base",- vectors_config=VectorParams(size=384, distance=Distance.COSINE)-)--# 索引文档-documents = [- {"id": 1, "text": "Python is a programming language", "source": "wiki"},- {"id": 2, "text": "Machine learning uses algorithms", "source": "textbook"},-]--points = [- PointStruct(- id=doc["id"],- vector=encoder.encode(doc["text"]).tolist(),- payload={"text": doc["text"], "source": doc["source"]}- )- for doc in documents-]-client.upsert(collection_name="knowledge_base", points=points)--# RAG 检索-def retrieve(query: str, top_k: int = 5) -> list[dict]:- query_vector = encoder.encode(query).tolist()- results = client.search(- collection_name="knowledge_base",- query_vector=query_vector,- limit=top_k- )- return [{"text": r.payload["text"], "score": r.score} for r in results]--# 在 RAG 流水线中使用-context = retrieve("What is Python?")-prompt = f"Context: {context}\n\nQuestion: What is Python?"-```--### 与 LangChain 集成--```python-from langchain_community.vectorstores import Qdrant-from langchain_community.embeddings import HuggingFaceEmbeddings--embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")-vectorstore = Qdrant.from_documents(documents, embeddings, url="http://localhost:6333", collection_name="docs")-retriever = vectorstore.as_retriever(search_kwargs={"k": 5})-```--### 与 LlamaIndex 集成--```python-from llama_index.vector_stores.qdrant import QdrantVectorStore-from llama_index.core import VectorStoreIndex, StorageContext--vector_store = QdrantVectorStore(client=client, collection_name="llama_docs")-storage_context = StorageContext.from_defaults(vector_store=vector_store)-index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)-query_engine = index.as_query_engine()-```--## 多向量支持--### 命名向量(不同 embedding 模型)--```python-from qdrant_client.models import VectorParams, Distance--# 包含多种向量类型的集合-client.create_collection(- collection_name="hybrid_search",- vectors_config={- "dense": VectorParams(size=384, distance=Distance.COSINE),- "sparse": VectorParams(size=30000, distance=Distance.DOT)- }-)--# 插入命名向量-client.upsert(- collection_name="hybrid_search",- points=[- PointStruct(- id=1,- vector={- "dense": dense_embedding,- "sparse": sparse_embedding- },- payload={"text": "document text"}- )- ]-)--# 搜索指定向量-results = client.search(- collection_name="hybrid_search",- query_vector=("dense", query_dense), # 指定使用哪个向量- limit=10-)-```--### 稀疏向量(BM25、SPLADE)--```python-from qdrant_client.models import SparseVectorParams, SparseIndexParams, SparseVector--# 包含稀疏向量的集合-client.create_collection(- collection_name="sparse_search",- vectors_config={},- sparse_vectors_config={"text": SparseVectorParams(index=SparseIndexParams(on_disk=False))}-)--# 插入稀疏向量-client.upsert(- collection_name="sparse_search",- points=[PointStruct(id=1, vector={"text": SparseVector(indices=[1, 5, 100], values=[0.5, 0.8, 0.2])}, payload={"text": "document"})]-)-```--## 量化(内存优化)--```python-from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType--# 标量量化(内存减少 4 倍)-client.create_collection(- collection_name="quantized",- vectors_config=VectorParams(size=384, distance=Distance.COSINE),- quantization_config=ScalarQuantization(- scalar=ScalarQuantizationConfig(- type=ScalarType.INT8,- quantile=0.99, # 裁剪异常值- always_ram=True # 将量化数据保留在 RAM 中- )- )-)--# 带重新评分的搜索-results = client.search(- collection_name="quantized",- query_vector=query,- search_params={"quantization": {"rescore": True}}, # 对 top 结果重新评分- limit=10-)-```--## Payload 索引--```python-from qdrant_client.models import PayloadSchemaType--# 创建 payload 索引以加速过滤-client.create_payload_index(- collection_name="documents",- field_name="category",- field_schema=PayloadSchemaType.KEYWORD-)--client.create_payload_index(- collection_name="documents",- field_name="timestamp",- field_schema=PayloadSchemaType.INTEGER-)--# 索引类型:KEYWORD、INTEGER、FLOAT、GEO、TEXT(全文)、BOOL-```--## 生产部署--### Qdrant Cloud--```python-from qdrant_client import QdrantClient--# 连接到 Qdrant Cloud-client = QdrantClient(- url="https://your-cluster.cloud.qdrant.io",- api_key="your-api-key"-)-```--### 性能调优--```python-# 优化搜索速度(更高召回率)-client.update_collection(- collection_name="documents",- hnsw_config=HnswConfigDiff(ef_construct=200, m=32)-)--# 优化索引速度(批量加载)-client.update_collection(- collection_name="documents",- optimizer_config={"indexing_threshold": 20000}-)-```--## 最佳实践--1. **批量操作** — 使用批量 upsert/search 提升效率-2. **Payload 索引** — 对过滤中使用的字段建立索引-3. **量化** — 对大型集合(>100 万向量)启用量化-4. **分片** — 对超过 1000 万向量的集合使用分片-5. **磁盘存储** — 对大型 payload 启用 `on_disk_payload`-6. **连接池** — 复用客户端实例--## 常见问题--**带过滤的搜索速度慢:**-```python-# 为过滤字段创建 payload 索引-client.create_payload_index(- collection_name="docs",- field_name="category",- field_schema=PayloadSchemaType.KEYWORD-)-```--**内存不足:**-```python-# 启用量化和磁盘存储-client.create_collection(- collection_name="large_collection",- vectors_config=VectorParams(size=384, distance=Distance.COSINE),- quantization_config=ScalarQuantization(...),- on_disk_payload=True-)-```--**连接问题:**-```python-# 使用超时和重试-client = QdrantClient(- host="localhost",- port=6333,- timeout=30,- prefer_grpc=True # gRPC 性能更佳-)-```--## 参考资料--- **[高级用法](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/qdrant/references/advanced-usage.md)** — 分布式模式、混合搜索、推荐系统-- **[故障排查](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/qdrant/references/troubleshooting.md)** — 常见问题、调试、性能调优--## 资源--- **GitHub**:https://github.com/qdrant/qdrant(22k+ stars)-- **文档**:https://qdrant.tech/documentation/-- **Python 客户端**:https://github.com/qdrant/qdrant-client-- **Cloud**:https://cloud.qdrant.io-- **版本**:1.12.0+-- **许可证**:Apache 2.0\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-stable-diffusion.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-stable-diffusion.mddeleted file mode 100644index f82f35ba95d..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-stable-diffusion.md+++ /dev/null@@ -1,542 +0,0 @@-----title: "Stable Diffusion 图像生成"-sidebar_label: "Stable Diffusion 图像生成"-description: "通过 HuggingFace Diffusers 使用 Stable Diffusion 模型实现最先进的文本到图像生成"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Stable Diffusion 图像生成--通过 HuggingFace Diffusers 使用 Stable Diffusion 模型实现最先进的文本到图像生成。适用于从文本 prompt(提示词)生成图像、执行图像到图像转换、图像修复(inpainting),或构建自定义扩散 pipeline。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/stable-diffusion` 安装 |-| 路径 | `optional-skills/mlops/stable-diffusion` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `diffusers>=0.30.0`, `transformers>=4.41.0`, `accelerate>=0.31.0`, `torch>=2.0.0` |-| 平台 | linux, macos, windows |-| 标签 | `Image Generation`, `Stable Diffusion`, `Diffusers`, `Text-to-Image`, `Multimodal`, `Computer Vision` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# Stable Diffusion 图像生成--使用 HuggingFace Diffusers 库通过 Stable Diffusion 生成图像的综合指南。--## 何时使用 Stable Diffusion--**在以下情况下使用 Stable Diffusion:**-- 从文本描述生成图像-- 执行图像到图像转换(风格迁移、增强)-- Inpainting(填充遮罩区域)-- Outpainting(将图像扩展至边界之外)-- 创建现有图像的变体-- 构建自定义图像生成工作流--**核心功能:**-- **文本到图像**:从自然语言 prompt 生成图像-- **图像到图像**:在文本引导下转换现有图像-- **Inpainting**:用上下文感知内容填充遮罩区域-- **ControlNet**:添加空间条件控制(边缘、姿态、深度)-- **LoRA 支持**:高效微调与风格适配-- **多模型支持**:支持 SD 1.5、SDXL、SD 3.0、Flux--**改用以下替代方案:**-- **DALL-E 3**:无需 GPU 的 API 生成-- **Midjourney**:艺术化、风格化输出-- **Imagen**:Google Cloud 集成-- **Leonardo.ai**:基于 Web 的创意工作流--## 快速开始--### 安装--```bash-pip install diffusers transformers accelerate torch-pip install xformers # Optional: memory-efficient attention-```--### 基础文本到图像--```python-from diffusers import DiffusionPipeline-import torch--# Load pipeline (auto-detects model type)-pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-)-pipe.to("cuda")--# Generate image-image = pipe(- "A serene mountain landscape at sunset, highly detailed",- num_inference_steps=50,- guidance_scale=7.5-).images[0]--image.save("output.png")-```--### 使用 SDXL(更高质量)--```python-from diffusers import AutoPipelineForText2Image-import torch--pipe = AutoPipelineForText2Image.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16,- variant="fp16"-)-pipe.to("cuda")--# Enable memory optimization-pipe.enable_model_cpu_offload()--image = pipe(- prompt="A futuristic city with flying cars, cinematic lighting",- height=1024,- width=1024,- num_inference_steps=30-).images[0]-```--## 架构概览--### 三支柱设计--Diffusers 围绕三个核心组件构建:--<!-- ascii-guard-ignore -->-```-Pipeline (orchestration)-├── Model (neural networks)-│ ├── UNet / Transformer (noise prediction)-│ ├── VAE (latent encoding/decoding)-│ └── Text Encoder (CLIP/T5)-└── Scheduler (denoising algorithm)-```-<!-- ascii-guard-ignore-end -->--### Pipeline 推理流程--```-Text Prompt → Text Encoder → Text Embeddings- ↓-Random Noise → [Denoising Loop] ← Scheduler- ↓- Predicted Noise- ↓- VAE Decoder → Final Image-```--## 核心概念--### Pipeline--Pipeline 编排完整工作流:--| Pipeline | 用途 |-|----------|---------|-| `StableDiffusionPipeline` | 文本到图像(SD 1.x/2.x) |-| `StableDiffusionXLPipeline` | 文本到图像(SDXL) |-| `StableDiffusion3Pipeline` | 文本到图像(SD 3.0) |-| `FluxPipeline` | 文本到图像(Flux 模型) |-| `StableDiffusionImg2ImgPipeline` | 图像到图像 |-| `StableDiffusionInpaintPipeline` | Inpainting |--### Scheduler--Scheduler 控制去噪过程:--| Scheduler | 步数 | 质量 | 适用场景 |-|-----------|-------|---------|----------|-| `EulerDiscreteScheduler` | 20-50 | 良好 | 默认选择 |-| `EulerAncestralDiscreteScheduler` | 20-50 | 良好 | 更多变化 |-| `DPMSolverMultistepScheduler` | 15-25 | 优秀 | 快速、高质量 |-| `DDIMScheduler` | 50-100 | 良好 | 确定性生成 |-| `LCMScheduler` | 4-8 | 良好 | 极速生成 |-| `UniPCMultistepScheduler` | 15-25 | 优秀 | 快速收敛 |--### 切换 Scheduler--```python-from diffusers import DPMSolverMultistepScheduler--# Swap for faster generation-pipe.scheduler = DPMSolverMultistepScheduler.from_config(- pipe.scheduler.config-)--# Now generate with fewer steps-image = pipe(prompt, num_inference_steps=20).images[0]-```--## 生成参数--### 关键参数--| 参数 | 默认值 | 说明 |-|-----------|---------|-------------|-| `prompt` | 必填 | 目标图像的文本描述 |-| `negative_prompt` | None | 图像中需要避免的内容 |-| `num_inference_steps` | 50 | 去噪步数(越多质量越好) |-| `guidance_scale` | 7.5 | Prompt 遵循程度(通常为 7-12) |-| `height`, `width` | 512/1024 | 输出尺寸(8 的倍数) |-| `generator` | None | 用于可复现性的 Torch generator |-| `num_images_per_prompt` | 1 | 批量大小 |--### 可复现生成--```python-import torch--generator = torch.Generator(device="cuda").manual_seed(42)--image = pipe(- prompt="A cat wearing a top hat",- generator=generator,- num_inference_steps=50-).images[0]-```--### Negative prompt--```python-image = pipe(- prompt="Professional photo of a dog in a garden",- negative_prompt="blurry, low quality, distorted, ugly, bad anatomy",- guidance_scale=7.5-).images[0]-```--## 图像到图像--在文本引导下转换现有图像:--```python-from diffusers import AutoPipelineForImage2Image-from PIL import Image--pipe = AutoPipelineForImage2Image.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-).to("cuda")--init_image = Image.open("input.jpg").resize((512, 512))--image = pipe(- prompt="A watercolor painting of the scene",- image=init_image,- strength=0.75, # How much to transform (0-1)- num_inference_steps=50-).images[0]-```--## Inpainting--填充遮罩区域:--```python-from diffusers import AutoPipelineForInpainting-from PIL import Image--pipe = AutoPipelineForInpainting.from_pretrained(- "runwayml/stable-diffusion-inpainting",- torch_dtype=torch.float16-).to("cuda")--image = Image.open("photo.jpg")-mask = Image.open("mask.png") # White = inpaint region--result = pipe(- prompt="A red car parked on the street",- image=image,- mask_image=mask,- num_inference_steps=50-).images[0]-```--## ControlNet--添加空间条件控制以实现精确控制:--```python-from diffusers import StableDiffusionControlNetPipeline, ControlNetModel-import torch--# Load ControlNet for edge conditioning-controlnet = ControlNetModel.from_pretrained(- "lllyasviel/control_v11p_sd15_canny",- torch_dtype=torch.float16-)--pipe = StableDiffusionControlNetPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- controlnet=controlnet,- torch_dtype=torch.float16-).to("cuda")--# Use Canny edge image as control-control_image = get_canny_image(input_image)--image = pipe(- prompt="A beautiful house in the style of Van Gogh",- image=control_image,- num_inference_steps=30-).images[0]-```--### 可用的 ControlNet--| ControlNet | 输入类型 | 适用场景 |-|------------|------------|----------|-| `canny` | 边缘图 | 保留结构 |-| `openpose` | 姿态骨架 | 人体姿态 |-| `depth` | 深度图 | 3D 感知生成 |-| `normal` | 法线图 | 表面细节 |-| `mlsd` | 线段 | 建筑线条 |-| `scribble` | 粗略草图 | 草图到图像 |--## LoRA 适配器--加载微调风格适配器:--```python-from diffusers import DiffusionPipeline--pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- torch_dtype=torch.float16-).to("cuda")--# Load LoRA weights-pipe.load_lora_weights("path/to/lora", weight_name="style.safetensors")--# Generate with LoRA style-image = pipe("A portrait in the trained style").images[0]--# Adjust LoRA strength-pipe.fuse_lora(lora_scale=0.8)--# Unload LoRA-pipe.unload_lora_weights()-```--### 多个 LoRA--```python-# Load multiple LoRAs-pipe.load_lora_weights("lora1", adapter_name="style")-pipe.load_lora_weights("lora2", adapter_name="character")--# Set weights for each-pipe.set_adapters(["style", "character"], adapter_weights=[0.7, 0.5])--image = pipe("A portrait").images[0]-```--## 内存优化--### 启用 CPU 卸载--```python-# Model CPU offload - moves models to CPU when not in use-pipe.enable_model_cpu_offload()--# Sequential CPU offload - more aggressive, slower-pipe.enable_sequential_cpu_offload()-```--### Attention 切片--```python-# Reduce memory by computing attention in chunks-pipe.enable_attention_slicing()--# Or specific chunk size-pipe.enable_attention_slicing("max")-```--### xFormers 内存高效 Attention--```python-# Requires xformers package-pipe.enable_xformers_memory_efficient_attention()-```--### 大图像的 VAE 切片--```python-# Decode latents in tiles for large images-pipe.enable_vae_slicing()-pipe.enable_vae_tiling()-```--## 模型变体--### 加载不同精度--```python-# FP16 (recommended for GPU)-pipe = DiffusionPipeline.from_pretrained(- "model-id",- torch_dtype=torch.float16,- variant="fp16"-)--# BF16 (better precision, requires Ampere+ GPU)-pipe = DiffusionPipeline.from_pretrained(- "model-id",- torch_dtype=torch.bfloat16-)-```--### 加载特定组件--```python-from diffusers import UNet2DConditionModel, AutoencoderKL--# Load custom VAE-vae = AutoencoderKL.from_pretrained("stabilityai/sd-vae-ft-mse")--# Use with pipeline-pipe = DiffusionPipeline.from_pretrained(- "stable-diffusion-v1-5/stable-diffusion-v1-5",- vae=vae,- torch_dtype=torch.float16-)-```--## 批量生成--高效生成多张图像:--```python-# Multiple prompts-prompts = [- "A cat playing piano",- "A dog reading a book",- "A bird painting a picture"-]--images = pipe(prompts, num_inference_steps=30).images--# Multiple images per prompt-images = pipe(- "A beautiful sunset",- num_images_per_prompt=4,- num_inference_steps=30-).images-```--## 常见工作流--### 工作流 1:高质量生成--```python-from diffusers import StableDiffusionXLPipeline, DPMSolverMultistepScheduler-import torch--# 1. Load SDXL with optimizations-pipe = StableDiffusionXLPipeline.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16,- variant="fp16"-)-pipe.to("cuda")-pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)-pipe.enable_model_cpu_offload()--# 2. Generate with quality settings-image = pipe(- prompt="A majestic lion in the savanna, golden hour lighting, 8k, detailed fur",- negative_prompt="blurry, low quality, cartoon, anime, sketch",- num_inference_steps=30,- guidance_scale=7.5,- height=1024,- width=1024-).images[0]-```--### 工作流 2:快速原型验证--```python-from diffusers import AutoPipelineForText2Image, LCMScheduler-import torch--# Use LCM for 4-8 step generation-pipe = AutoPipelineForText2Image.from_pretrained(- "stabilityai/stable-diffusion-xl-base-1.0",- torch_dtype=torch.float16-).to("cuda")--# Load LCM LoRA for fast generation-pipe.load_lora_weights("latent-consistency/lcm-lora-sdxl")-pipe.scheduler = LCMScheduler.from_config(pipe.scheduler.config)-pipe.fuse_lora()--# Generate in ~1 second-image = pipe(- "A beautiful landscape",- num_inference_steps=4,- guidance_scale=1.0-).images[0]-```--## 常见问题--**CUDA 内存不足:**-```python-# Enable memory optimizations-pipe.enable_model_cpu_offload()-pipe.enable_attention_slicing()-pipe.enable_vae_slicing()--# Or use lower precision-pipe = DiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16)-```--**黑色/噪声图像:**-```python-# Check VAE configuration-# Use safety checker bypass if needed-pipe.safety_checker = None--# Ensure proper dtype consistency-pipe = pipe.to(dtype=torch.float16)-```--**生成速度慢:**-```python-# Use faster scheduler-from diffusers import DPMSolverMultistepScheduler-pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)--# Reduce steps-image = pipe(prompt, num_inference_steps=20).images[0]-```--## 参考资料--- **[高级用法](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/stable-diffusion/references/advanced-usage.md)** - 自定义 pipeline、微调、部署-- **[故障排查](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/stable-diffusion/references/troubleshooting.md)** - 常见问题与解决方案--## 资源--- **文档**:https://huggingface.co/docs/diffusers-- **代码仓库**:https://github.com/huggingface/diffusers-- **模型中心**:https://huggingface.co/models?library=diffusers-- **Discord**:https://discord.gg/diffusers\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.mddeleted file mode 100644index 225ac0bc70a..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning.md+++ /dev/null@@ -1,477 +0,0 @@-----title: "使用 TRL 进行微调 — TRL:面向 LLM RLHF 的 SFT、DPO、PPO、GRPO 及奖励建模"-sidebar_label: "使用 TRL 进行微调"-description: "TRL:面向 LLM RLHF 的 SFT、DPO、PPO、GRPO 及奖励建模"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# 使用 TRL 进行微调--TRL:面向 LLM RLHF 的 SFT、DPO、PPO、GRPO 及奖励建模。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/trl-fine-tuning` 安装 |-| 路径 | `optional-skills/mlops/training/trl-fine-tuning` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `trl`, `transformers`, `datasets`, `peft`, `accelerate`, `torch` |-| 平台 | linux, macos, windows |-| 标签 | `Post-Training`, `TRL`, `Reinforcement Learning`, `Fine-Tuning`, `SFT`, `DPO`, `PPO`, `GRPO`, `RLHF`, `Preference Alignment`, `HuggingFace` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# TRL - Transformer Reinforcement Learning--## 快速开始--TRL 提供用于将语言模型与人类偏好对齐的后训练(post-training)方法。--**安装**:-```bash-pip install trl transformers datasets peft accelerate-```--**监督微调(SFT)**(指令微调):-```python-from trl import SFTTrainer--trainer = SFTTrainer(- model="Qwen/Qwen2.5-0.5B",- train_dataset=dataset, # Prompt-completion pairs-)-trainer.train()-```--**DPO**(偏好对齐):-```python-from trl import DPOTrainer, DPOConfig--config = DPOConfig(output_dir="model-dpo", beta=0.1)-trainer = DPOTrainer(- model=model,- args=config,- train_dataset=preference_dataset, # chosen/rejected pairs- processing_class=tokenizer-)-trainer.train()-```--## 常见工作流--### 工作流 1:完整 RLHF 流水线(SFT → 奖励模型 → PPO)--从基础模型到人类对齐模型的完整流水线。--复制此检查清单:--```-RLHF Training:-- [ ] Step 1: Supervised fine-tuning (SFT)-- [ ] Step 2: Train reward model-- [ ] Step 3: PPO reinforcement learning-- [ ] Step 4: Evaluate aligned model-```--**第 1 步:监督微调**--在指令跟随数据上训练基础模型:--```python-from transformers import AutoModelForCausalLM, AutoTokenizer-from trl import SFTTrainer, SFTConfig-from datasets import load_dataset--# Load model-model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B")-tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B")--# Load instruction dataset-dataset = load_dataset("trl-lib/Capybara", split="train")--# Configure training-training_args = SFTConfig(- output_dir="Qwen2.5-0.5B-SFT",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=2e-5,- logging_steps=10,- save_strategy="epoch"-)--# Train-trainer = SFTTrainer(- model=model,- args=training_args,- train_dataset=dataset,- tokenizer=tokenizer-)-trainer.train()-trainer.save_model()-```--**第 2 步:训练奖励模型**--训练模型以预测人类偏好:--```python-from transformers import AutoModelForSequenceClassification-from trl import RewardTrainer, RewardConfig--# Load SFT model as base-model = AutoModelForSequenceClassification.from_pretrained(- "Qwen2.5-0.5B-SFT",- num_labels=1 # Single reward score-)-tokenizer = AutoTokenizer.from_pretrained("Qwen2.5-0.5B-SFT")--# Load preference data (chosen/rejected pairs)-dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")--# Configure training-training_args = RewardConfig(- output_dir="Qwen2.5-0.5B-Reward",- per_device_train_batch_size=2,- num_train_epochs=1,- learning_rate=1e-5-)--# Train reward model-trainer = RewardTrainer(- model=model,- args=training_args,- processing_class=tokenizer,- train_dataset=dataset-)-trainer.train()-trainer.save_model()-```--**第 3 步:PPO 强化学习**--使用奖励模型优化策略:--```bash-python -m trl.scripts.ppo \- --model_name_or_path Qwen2.5-0.5B-SFT \- --reward_model_path Qwen2.5-0.5B-Reward \- --dataset_name trl-internal-testing/descriptiveness-sentiment-trl-style \- --output_dir Qwen2.5-0.5B-PPO \- --learning_rate 3e-6 \- --per_device_train_batch_size 64 \- --total_episodes 10000-```--**第 4 步:评估**--```python-from transformers import pipeline--# Load aligned model-generator = pipeline("text-generation", model="Qwen2.5-0.5B-PPO")--# Test-prompt = "Explain quantum computing to a 10-year-old"-output = generator(prompt, max_length=200)[0]["generated_text"]-print(output)-```--### 工作流 2:使用 DPO 进行简单偏好对齐--无需奖励模型即可对齐模型偏好。--复制此检查清单:--```-DPO Training:-- [ ] Step 1: Prepare preference dataset-- [ ] Step 2: Configure DPO-- [ ] Step 3: Train with DPOTrainer-- [ ] Step 4: Evaluate alignment-```--**第 1 步:准备偏好数据集**--数据集格式:-```json-{- "prompt": "What is the capital of France?",- "chosen": "The capital of France is Paris.",- "rejected": "I don't know."-}-```--加载数据集:-```python-from datasets import load_dataset--dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")-# Or load your own-# dataset = load_dataset("json", data_files="preferences.json")-```--**第 2 步:配置 DPO**--```python-from trl import DPOConfig--config = DPOConfig(- output_dir="Qwen2.5-0.5B-DPO",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=5e-7,- beta=0.1, # KL penalty strength- max_prompt_length=512,- max_length=1024,- logging_steps=10-)-```--**第 3 步:使用 DPOTrainer 训练**--```python-from transformers import AutoModelForCausalLM, AutoTokenizer-from trl import DPOTrainer--model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")-tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")--trainer = DPOTrainer(- model=model,- args=config,- train_dataset=dataset,- processing_class=tokenizer-)--trainer.train()-trainer.save_model()-```--**CLI 替代方式**:-```bash-trl dpo \- --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \- --dataset_name argilla/Capybara-Preferences \- --output_dir Qwen2.5-0.5B-DPO \- --per_device_train_batch_size 4 \- --learning_rate 5e-7 \- --beta 0.1-```--### 工作流 3:使用 GRPO 进行内存高效的在线 RL--以最小内存占用进行强化学习训练。--关于深入的 GRPO 指导——奖励函数设计、关键训练洞察(损失行为、模式崩溃、调参)以及高级多阶段模式——请参阅 **[references/grpo-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/grpo-training.md)**。生产就绪的训练脚本位于 **[templates/basic_grpo_training.py](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/templates/basic_grpo_training.py)**。--复制此检查清单:--```-GRPO Training:-- [ ] Step 1: Define reward function-- [ ] Step 2: Configure GRPO-- [ ] Step 3: Train with GRPOTrainer-```--**第 1 步:定义奖励函数**--```python-def reward_function(completions, **kwargs):- """- Compute rewards for completions.-- Args:- completions: List of generated texts-- Returns:- List of reward scores (floats)- """- rewards = []- for completion in completions:- # Example: reward based on length and unique words- score = len(completion.split()) # Favor longer responses- score += len(set(completion.lower().split())) # Reward unique words- rewards.append(score)- return rewards-```--或使用奖励模型:-```python-from transformers import pipeline--reward_model = pipeline("text-classification", model="reward-model-path")--def reward_from_model(completions, prompts, **kwargs):- # Combine prompt + completion- full_texts = [p + c for p, c in zip(prompts, completions)]- # Get reward scores- results = reward_model(full_texts)- return [r["score"] for r in results]-```--**第 2 步:配置 GRPO**--```python-from trl import GRPOConfig--config = GRPOConfig(- output_dir="Qwen2-GRPO",- per_device_train_batch_size=4,- num_train_epochs=1,- learning_rate=1e-5,- num_generations=4, # Generate 4 completions per prompt- max_new_tokens=128-)-```--**第 3 步:使用 GRPOTrainer 训练**--```python-from datasets import load_dataset-from trl import GRPOTrainer--# Load prompt-only dataset-dataset = load_dataset("trl-lib/tldr", split="train")--trainer = GRPOTrainer(- model="Qwen/Qwen2-0.5B-Instruct",- reward_funcs=reward_function, # Your reward function- args=config,- train_dataset=dataset-)--trainer.train()-```--**CLI**:-```bash-trl grpo \- --model_name_or_path Qwen/Qwen2-0.5B-Instruct \- --dataset_name trl-lib/tldr \- --output_dir Qwen2-GRPO \- --num_generations 4-```--## 何时使用 TRL 及替代方案--**适合使用 TRL 的场景:**-- 需要将模型与人类偏好对齐-- 拥有偏好数据(chosen/rejected 对)-- 希望使用强化学习(PPO、GRPO)-- 需要训练奖励模型-- 执行完整 RLHF 流水线--**方法选择**:-- **SFT**:拥有 prompt-completion 对,需要基础指令跟随-- **DPO**:拥有偏好数据,需要简单对齐(无需奖励模型)-- **PPO**:拥有奖励模型,需要对 RL 进行最大程度的控制-- **GRPO**:内存受限,需要在线 RL-- **奖励模型**:构建 RLHF 流水线,需要对生成内容评分--**改用替代方案的场景:**-- **HuggingFace Trainer**:无需 RL 的基础微调-- **Axolotl**:基于 YAML 的训练配置-- **LitGPT**:教学用途、极简微调-- **Unsloth**:快速 LoRA 训练--## 常见问题--**问题:DPO 训练时显存溢出(OOM)**--减小批次大小和序列长度:-```python-config = DPOConfig(- per_device_train_batch_size=1, # Reduce from 4- max_length=512, # Reduce from 1024- gradient_accumulation_steps=8 # Maintain effective batch-)-```--或启用梯度检查点:-```python-model.gradient_checkpointing_enable()-```--**问题:对齐质量差**--调整 beta 参数:-```python-# Higher beta = more conservative (stays closer to reference)-config = DPOConfig(beta=0.5) # Default 0.1--# Lower beta = more aggressive alignment-config = DPOConfig(beta=0.01)-```--**问题:奖励模型无法学习**--检查损失类型和学习率:-```python-config = RewardConfig(- learning_rate=1e-5, # Try different LR- num_train_epochs=3 # Train longer-)-```--确保偏好数据集有明确的优劣区分:-```python-# Verify dataset-print(dataset[0])-# Should have clear chosen > rejected-```--**问题:PPO 训练不稳定**--调整 KL 系数:-```python-config = PPOConfig(- kl_coef=0.1, # Increase from 0.05- cliprange=0.1 # Reduce from 0.2-)-```--## 高级主题--**SFT 训练指南**:参阅 [references/sft-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/sft-training.md),了解数据集格式、chat template、packing 策略及多 GPU 训练。--**DPO 变体**:参阅 [references/dpo-variants.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/dpo-variants.md),了解 IPO、cDPO、RPO 及其他 DPO 损失函数与推荐超参数。--**奖励建模**:参阅 [references/reward-modeling.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/reward-modeling.md),了解结果奖励与过程奖励、Bradley-Terry 损失及奖励模型评估。--**在线 RL 方法**:参阅 [references/online-rl.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/online-rl.md),了解 PPO、GRPO、RLOO 及 OnlineDPO 的详细配置。--**GRPO 深度解析**:参阅 [references/grpo-training.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/references/grpo-training.md),获取专家级 GRPO 模式——奖励函数设计理念、训练洞察(为何损失上升、模式崩溃检测)、超参数调优、多阶段训练及故障排查。生产就绪模板位于 [templates/basic_grpo_training.py](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/training/trl-fine-tuning/templates/basic_grpo_training.py)。--## 硬件要求--- **GPU**:NVIDIA(需要 CUDA)-- **显存(VRAM)**:取决于模型和方法- - SFT 7B:16GB(使用 LoRA)- - DPO 7B:24GB(存储参考模型)- - PPO 7B:40GB(策略模型 + 奖励模型)- - GRPO 7B:24GB(内存效率更高)-- **多 GPU**:通过 `accelerate` 支持-- **混合精度**:推荐 BF16(A100/H100)--**内存优化**:-- 所有方法均可使用 LoRA/QLoRA-- 启用梯度检查点-- 使用更小的批次大小配合梯度累积--## 资源--- 文档:https://huggingface.co/docs/trl/-- GitHub:https://github.com/huggingface/trl-- 论文:- - "Training language models to follow instructions with human feedback"(InstructGPT,2022)- - "Direct Preference Optimization: Your Language Model is Secretly a Reward Model"(DPO,2023)- - "Group Relative Policy Optimization"(GRPO,2024)-- 示例:https://github.com/huggingface/trl/tree/main/examples/scripts\ No newline at end of filediff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-whisper.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-whisper.mddeleted file mode 100644index cb2bcd136ae..00000000000--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/mlops/mlops-whisper.md+++ /dev/null@@ -1,336 +0,0 @@-----title: "Whisper — OpenAI 的通用语音识别模型"-sidebar_label: "Whisper"-description: "OpenAI 的通用语音识别模型"------{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}--# Whisper--OpenAI 的通用语音识别模型。支持 99 种语言、转录、翻译为英语及语言识别。提供六种模型规格,从 tiny(3900 万参数)到 large(15.5 亿参数)。适用于语音转文字、播客转录或多语言音频处理。是鲁棒多语言 ASR(自动语音识别)的首选。--## Skill 元数据--| | |-|---|---|-| 来源 | 可选 — 通过 `hermes skills install official/mlops/whisper` 安装 |-| 路径 | `optional-skills/mlops/whisper` |-| 版本 | `1.0.0` |-| 作者 | Orchestra Research |-| 许可证 | MIT |-| 依赖项 | `openai-whisper`, `transformers`, `torch` |-| 平台 | linux, macos |-| 标签 | `Whisper`, `Speech Recognition`, `ASR`, `Multimodal`, `Multilingual`, `OpenAI`, `Speech-To-Text`, `Transcription`, `Translation`, `Audio Processing` |--## 参考:完整 SKILL.md--:::info-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。-:::--# Whisper - 鲁棒语音识别--OpenAI 的多语言语音识别模型。--## 何时使用 Whisper--**适用场景:**-- 语音转文字转录(99 种语言)-- 播客/视频转录-- 会议记录自动化-- 翻译为英语-- 嘈杂音频转录-- 多语言音频处理--**指标**:-- **GitHub 72,900+ 星**-- 支持 99 种语言-- 基于 68 万小时音频训练-- MIT 许可证--**改用其他替代方案的情况**:-- **AssemblyAI**:托管 API,支持说话人分离-- **Deepgram**:实时流式 ASR-- **Google Speech-to-Text**:基于云端--## 快速开始--### 安装--```bash-# Requires Python 3.8-3.11-pip install -U openai-whisper--# Requires ffmpeg-# macOS: brew install ffmpeg-# Ubuntu: sudo apt install ffmpeg-# Windows: choco install ffmpeg-```--### 基本转录--```python-import whisper--# Load model-model = whisper.load_model("base")--# Transcribe-result = model.transcribe("audio.mp3")--# Print text-print(result["text"])--# Access segments-for segment in result["segments"]:- print(f"[{segment['start']:.2f}s - {segment['end']:.2f}s] {segment['text']}")-```--## 模型规格--```python-# Available models-models = ["tiny", "base", "small", "medium", "large", "turbo"]--# Load specific model-model = whisper.load_model("turbo") # Fastest, good quality-```--| 模型 | 参数量 | 仅英语 | 多语言 | 速度 | 显存 |-|-------|------------|--------------|--------------|-------|------|-| tiny | 39M | ✓ | ✓ | ~32x | ~1 GB |-| base | 74M | ✓ | ✓ | ~16x | ~1 GB |-| small | 244M | ✓ | ✓ | ~6x | ~2 GB |-| medium | 769M | ✓ | ✓ | ~2x | ~5 GB |-| large | 1550M | ✗ | ✓ | 1x | ~10 GB |-| turbo | 809M | ✗ | ✓ | ~8x | ~6 GB |--**推荐**:追求最佳速度/质量比使用 `turbo`,原型开发使用 `base`--## 转录选项--### 语言指定--```python-# Auto-detect language-result = model.transcribe("audio.mp3")--# Specify language (faster)-result = model.transcribe("audio.mp3", language="en")--# Supported: en, es, fr, de, it, pt, ru, ja, ko, zh, and 89 more-```--### 任务选择--```python-# Transcription (default)-result = model.transcribe("audio.mp3", task="transcribe")--# Translation to English-result = model.transcribe("spanish.mp3", task="translate")-# Input: Spanish audio → Output: English text-```--### 初始 prompt(提示词)--```python-# Improve accuracy with context-result = model.transcribe(- "audio.mp3",- initial_prompt="This is a technical podcast about machine learning and AI."-)--# Helps with:-# - Technical terms-# - Proper nouns-# - Domain-specific vocabulary-```--### 时间戳--```python-# Word-level timestamps-result = model.transcribe("audio.mp3", word_timestamps=True)--for segment in result["segments"]:- for word in segment["words"]:- print(f"{word['word']} ({word['start']:.2f}s - {word['end']:.2f}s)")-```--### 温度回退--```python-# Retry with different temperatures if confidence low-result = model.transcribe(- "audio.mp3",- temperature=(0.0, 0.2, 0.4, 0.6, 0.8, 1.0)-)-```--## 命令行用法--```bash-# Basic transcription-whisper audio.mp3--# Specify model-whisper audio.mp3 --model turbo--# Output formats-whisper audio.mp3 --output_format txt # Plain text-whisper audio.mp3 --output_format srt # Subtitles-whisper audio.mp3 --output_format vtt # WebVTT-whisper audio.mp3 --output_format json # JSON with timestamps--# Language-whisper audio.mp3 --language Spanish--# Translation-whisper spanish.mp3 --task translate-```--## 批量处理--```python-import os--audio_files = ["file1.mp3", "file2.mp3", "file3.mp3"]--for audio_file in audio_files:- print(f"Transcribing {audio_file}...")- result = model.transcribe(audio_file)-- # Save to file- output_file = audio_file.replace(".mp3", ".txt")- with open(output_file, "w") as f:- f.write(result["text"])-```--## 实时转录--```python-# For streaming audio, use faster-whisper-# pip install faster-whisper--from faster_whisper import WhisperModel--model = WhisperModel("base", device="cuda", compute_type="float16")--# Transcribe with streaming-segments, info = model.transcribe("audio.mp3", beam_size=5)--for segment in segments:- print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")-```--## GPU 加速--```python-import whisper--# Automatically uses GPU if available-model = whisper.load_model("turbo")--# Force CPU-model = whisper.load_model("turbo", device="cpu")--# Force GPU-model = whisper.load_model("turbo", device="cuda")--# 10-20× faster on GPU-```--## 与其他工具集成--### 字幕生成--```bash-# Generate SRT subtitles-whisper video.mp4 --output_format srt --language English--# Output: video.srt-```--### 与 LangChain 集成--```python-from langchain.document_loaders import WhisperTranscriptionLoader--loader = WhisperTranscriptionLoader(file_path="audio.mp3")-docs = loader.load()--# Use transcription in RAG-from langchain_chroma import Chroma-from langchain_openai import OpenAIEmbeddings--vectorstore = Chroma.from_documents(docs, OpenAIEmbeddings())-```--### 从视频中提取音频--```bash-# Use ffmpeg to extract audio-ffmpeg -i video.mp4 -vn -acodec pcm_s16le audio.wav--# Then transcribe-whisper audio.wav-```--## 最佳实践--1. **使用 turbo 模型** — 英语场景下速度/质量最优-2. **指定语言** — 比自动检测更快-3. **添加初始 prompt** — 提升专业术语识别准确率-4. **使用 GPU** — 速度提升 10–20 倍-5. **批量处理** — 效率更高-6. **转换为 WAV** — 兼容性更好-7. **切分长音频** — 每段不超过 30 分钟-8. **确认语言支持情况** — 不同语言质量有差异-9. **使用 faster-whisper** — 比 openai-whisper 快 4 倍-10. **监控显存** — 根据硬件配置选择模型规格--## 性能--| 模型 | 实时倍率(CPU) | 实时倍率(GPU) |-|-------|------------------------|------------------------|-| tiny | ~0.32 | ~0.01 |-| base | ~0.16 | ~0.01 |-| turbo | ~0.08 | ~0.01 |-| large | ~1.0 | ~0.05 |--*实时倍率:0.1 表示比实时速度快 10 倍*--## 语言支持--主要支持语言:-- 英语(en)-- 西班牙语(es)-- 法语(fr)-- 德语(de)-- 意大利语(it)-- 葡萄牙语(pt)-- 俄语(ru)-- 日语(ja)-- 韩语(ko)-- 中文(zh)--完整列表:共 99 种语言--## 局限性--1. **幻觉问题** — 可能重复或生成不存在的文本-2. **长音频准确率** — 超过 30 分钟后质量下降-3. **说话人识别** — 不支持说话人分离-4. **口音** — 质量因口音而异-5. **背景噪音** — 可能影响准确率-6. **实时延迟** — 不适合实时字幕场景--## 资源--- **GitHub**:https://github.com/openai/whisper ⭐ 72,900+-- **论文**:https://arxiv.org/abs/2212.04356-- **模型卡片**:https://github.com/openai/whisper/blob/main/model-card.md-- **Colab**:可在仓库中获取-- **许可证**:MIT\ No newline at end of filediff --git a/website/sidebars.ts b/website/sidebars.tsindex dab078f6da0..d03bd085b3a 100644--- a/website/sidebars.ts+++ b/website/sidebars.ts@@ -186,7 +186,6 @@ const sidebars: SidebarsConfig = {'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex','user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use','user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent',- 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode',],},{@@ -199,7 +198,6 @@ const sidebars: SidebarsConfig = {'user-guide/skills/bundled/creative/creative-ascii-video','user-guide/skills/bundled/creative/creative-baoyu-infographic','user-guide/skills/bundled/creative/creative-claude-design',- 'user-guide/skills/bundled/creative/creative-design-md','user-guide/skills/bundled/creative/creative-humanizer','user-guide/skills/bundled/creative/creative-manim-video','user-guide/skills/bundled/creative/creative-p5js',@@ -232,8 +230,6 @@ const sidebars: SidebarsConfig = {key: 'skills-bundled-media',collapsed: true,items: [- 'user-guide/skills/bundled/media/media-gif-search',- 'user-guide/skills/bundled/media/media-songsee','user-guide/skills/bundled/media/media-youtube-content',],},@@ -252,20 +248,15 @@ const sidebars: SidebarsConfig = {key: 'skills-bundled-productivity',collapsed: true,items: [- 'user-guide/skills/bundled/productivity/productivity-airtable',- 'user-guide/skills/bundled/productivity/productivity-box','user-guide/skills/bundled/productivity/productivity-document-to-action-items',- 'user-guide/skills/bundled/productivity/productivity-docx','user-guide/skills/bundled/productivity/productivity-google-workspace','user-guide/skills/bundled/productivity/productivity-maps','user-guide/skills/bundled/productivity/productivity-meeting-action-items',- 'user-guide/skills/bundled/productivity/productivity-notion',+ 'user-guide/skills/bundled/productivity/productivity-microsoft-office','user-guide/skills/bundled/productivity/productivity-pdf',- 'user-guide/skills/bundled/productivity/productivity-powerpoint','user-guide/skills/bundled/productivity/productivity-product-price-monitor','user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline','user-guide/skills/bundled/productivity/productivity-weekly-review-planning',- 'user-guide/skills/bundled/productivity/productivity-xlsx',],},{@@ -277,7 +268,6 @@ const sidebars: SidebarsConfig = {'user-guide/skills/bundled/research/research-arxiv','user-guide/skills/bundled/research/research-competitor-news-monitor','user-guide/skills/bundled/research/research-grounded-citations',- 'user-guide/skills/bundled/research/research-llm-wiki',],},{@@ -298,10 +288,6 @@ const sidebars: SidebarsConfig = {'user-guide/skills/bundled/software-development/software-development-codebase-inspection','user-guide/skills/bundled/software-development/software-development-dogfood','user-guide/skills/bundled/software-development/software-development-github',- 'user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring',- 'user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom',- 'user-guide/skills/bundled/software-development/software-development-node-inspect-debugger',- 'user-guide/skills/bundled/software-development/software-development-python-debugpy','user-guide/skills/bundled/software-development/software-development-requesting-code-review','user-guide/skills/bundled/software-development/software-development-simplify-code','user-guide/skills/bundled/software-development/software-development-spike',@@ -337,6 +323,7 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow','user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok','user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho',+ 'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-opencode','user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands',],},@@ -370,7 +357,6 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/creative/creative-anatomy','user-guide/skills/optional/creative/creative-archify','user-guide/skills/optional/creative/creative-ascii-art',- 'user-guide/skills/optional/creative/creative-audiocraft-audio-generation','user-guide/skills/optional/creative/creative-auteur','user-guide/skills/optional/creative/creative-baoyu-article-illustrator','user-guide/skills/optional/creative/creative-baoyu-comic',@@ -379,6 +365,7 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/creative/creative-comfyui','user-guide/skills/optional/creative/creative-concept-diagrams','user-guide/skills/optional/creative/creative-creative-ideation',+ 'user-guide/skills/optional/creative/creative-design-md','user-guide/skills/optional/creative/creative-draw-your-font','user-guide/skills/optional/creative/creative-dream-loop','user-guide/skills/optional/creative/creative-excalidraw',@@ -489,6 +476,16 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/mcp/mcp-mcporter',],},+ {+ type: 'category',+ label: 'media',+ key: 'skills-optional-media',+ collapsed: true,+ items: [+ 'user-guide/skills/optional/media/media-gif-search',+ 'user-guide/skills/optional/media/media-songsee',+ ],+ },{type: 'category',label: 'mlops',@@ -498,39 +495,26 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/mlops/mlops-accelerate','user-guide/skills/optional/mlops/mlops-training-axolotl','user-guide/skills/optional/mlops/mlops-chroma',- 'user-guide/skills/optional/mlops/mlops-clip','user-guide/skills/optional/mlops/mlops-research-dspy','user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness','user-guide/skills/optional/mlops/mlops-faiss','user-guide/skills/optional/mlops/mlops-flash-attention',- 'user-guide/skills/optional/mlops/mlops-guidance',- 'user-guide/skills/optional/mlops/mlops-models-huggingface-hub',- 'user-guide/skills/optional/mlops/mlops-huggingface-tokenizers',- 'user-guide/skills/optional/mlops/mlops-instructor','user-guide/skills/optional/mlops/mlops-lambda-labs','user-guide/skills/optional/mlops/mlops-inference-llama-cpp',- 'user-guide/skills/optional/mlops/mlops-llava','user-guide/skills/optional/mlops/mlops-modal','user-guide/skills/optional/mlops/mlops-nemo-curator','user-guide/skills/optional/mlops/mlops-obliteratus',- 'user-guide/skills/optional/mlops/mlops-inference-outlines','user-guide/skills/optional/mlops/mlops-peft',- 'user-guide/skills/optional/mlops/mlops-pinecone','user-guide/skills/optional/mlops/mlops-pytorch-fsdp','user-guide/skills/optional/mlops/mlops-pytorch-lightning',- 'user-guide/skills/optional/mlops/mlops-qdrant','user-guide/skills/optional/mlops/mlops-saelens','user-guide/skills/optional/mlops/mlops-models-segment-anything-model','user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm','user-guide/skills/optional/mlops/mlops-simpo','user-guide/skills/optional/mlops/mlops-slime',- 'user-guide/skills/optional/mlops/mlops-stable-diffusion','user-guide/skills/optional/mlops/mlops-tensorrt-llm','user-guide/skills/optional/mlops/mlops-torchtitan',- 'user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning','user-guide/skills/optional/mlops/mlops-training-unsloth',- 'user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases',- 'user-guide/skills/optional/mlops/mlops-whisper',],},{@@ -550,11 +534,14 @@ const sidebars: SidebarsConfig = {key: 'skills-optional-productivity',collapsed: true,items: [+ 'user-guide/skills/optional/productivity/productivity-airtable',+ 'user-guide/skills/optional/productivity/productivity-box','user-guide/skills/optional/productivity/productivity-canvas','user-guide/skills/optional/productivity/productivity-decision-questionnaire','user-guide/skills/optional/productivity/productivity-here-now','user-guide/skills/optional/productivity/productivity-live-dashboard','user-guide/skills/optional/productivity/productivity-memento-flashcards',+ 'user-guide/skills/optional/productivity/productivity-notion','user-guide/skills/optional/productivity/productivity-property-listings','user-guide/skills/optional/productivity/productivity-shop','user-guide/skills/optional/productivity/productivity-shopify',@@ -575,9 +562,9 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/research/research-drug-discovery','user-guide/skills/optional/research/research-duckduckgo-search','user-guide/skills/optional/research/research-gitnexus-explorer',+ 'user-guide/skills/optional/research/research-llm-wiki','user-guide/skills/optional/research/research-osint-investigation','user-guide/skills/optional/research/research-parallel-cli',- 'user-guide/skills/optional/research/research-pinecone-research','user-guide/skills/optional/research/research-qmd','user-guide/skills/optional/research/research-research-paper-writing','user-guide/skills/optional/research/research-rss-feeds',@@ -626,7 +613,11 @@ const sidebars: SidebarsConfig = {'user-guide/skills/optional/software-development/software-development-ast-grep','user-guide/skills/optional/software-development/software-development-code-wiki','user-guide/skills/optional/software-development/software-development-grill-me',+ 'user-guide/skills/optional/software-development/software-development-hermes-agent-skill-authoring',+ 'user-guide/skills/optional/software-development/software-development-inspecting-hermes-desktop-dom',+ 'user-guide/skills/optional/software-development/software-development-node-inspect-debugger','user-guide/skills/optional/software-development/software-development-pr-lens',+ 'user-guide/skills/optional/software-development/software-development-python-debugpy','user-guide/skills/optional/software-development/software-development-rest-graphql-debug','user-guide/skills/optional/software-development/software-development-subagent-driven-development',],