[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MA7FA9AA7F90YRE6YTPMHR":3,"skill-same:01M6MA7FA9AA7F90YRE6YTPMHR":105},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":62,"ownerHtmlUrl":63,"ownerBlogUrl":64,"ownerDescription":65,"updatedAt":66,"install":67,"resources":80},"01M6MA7FA9AA7F90YRE6YTPMHR","guidance",null,"Constrains LLM output during generation with Guidance (Microsoft Research), using regex, select() choices, context-free grammars, token healing, and @guidance functions, with Anthropic, OpenAI, Transformers, and llama.cpp backends. Use when you need generated text to match a regex or fixed format such as dates, emails, or IDs. Use when you need guaranteed valid JSON, XML, or code from a model. Use when building multi-step generation workflows or ReAct-style agents with Python control flow. Use when classifying text into fixed categories with select(). Use when running local models and wanting grammar constraints. Not for Pydantic validation with automatic retries; use Instructor for that.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[5,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"local","automatic","for","categories","you","retries","structured output","free","as","regex","python","enforcement","context","text","applications","ids","react","workflows","valid","2026-11-10 10:12:30",false,"---\nname: guidance\ndescription: Constrains LLM output during generation with Guidance (Microsoft Research), using regex, select() choices, context-free grammars, token healing, and @guidance functions, with Anthropic, OpenAI, Transformers, and llama.cpp backends. Use when you need generated text to match a regex or fixed format such as dates, emails, or IDs. Use when you need guaranteed valid JSON, XML, or code from a model. Use when building multi-step generation workflows or ReAct-style agents with Python control flow. Use when classifying text into fixed categories with select(). Use when running local models and wanting grammar constraints. Not for Pydantic validation with automatic retries; use Instructor for that.\nlicense: MIT\nmetadata:\n  version: 1.0.0\n  category: llm-applications\n  maintainer: Kalaris Labs\n  tags: Prompt Engineering, Guidance, Constrained Generation, Structured Output, JSON Validation, Grammar, Microsoft Research, Format Enforcement, Multi-Step Workflows\n  dependencies: guidance, transformers\n---\n\n# Guidance: Constrained LLM Generation\n\n## When to Use This Skill\n\nUse Guidance when you need to:\n- **Control LLM output syntax** with regex or grammars\n- **Guarantee valid JSON\u002FXML\u002Fcode** generation\n- **Reduce latency** vs traditional prompting approaches\n- **Enforce structured formats** (dates, emails, IDs, etc.)\n- **Build multi-step workflows** with Pythonic control flow\n- **Prevent invalid outputs** through grammatical constraints\n\n\n## Installation\n\n```bash\n# Base installation\npip install guidance\n\n# With specific backends\npip install guidance[transformers]  # Hugging Face models\npip install guidance[llama_cpp]     # llama.cpp models\n```\n\n## Quick Start\n\n### Basic Example: Structured Generation\n\n```python\nfrom guidance import models, gen\n\n# Load model (supports OpenAI, Transformers, llama.cpp)\nlm = models.OpenAI(\"gpt-4\")\n\n# Generate with constraints\nresult = lm + \"The capital of France is \" + gen(\"capital\", max_tokens=5)\n\nprint(result[\"capital\"])  # \"Paris\"\n```\n\n### With Anthropic Claude\n\n```python\nfrom guidance import models, gen, system, user, assistant\n\n# Configure Claude\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Use context managers for chat format\nwith system():\n    lm += \"You are a helpful assistant.\"\n\nwith user():\n    lm += \"What is the capital of France?\"\n\nwith assistant():\n    lm += gen(max_tokens=20)\n```\n\n## Core Concepts\n\n### 1. Context Managers\n\nGuidance uses Pythonic context managers for chat-style interactions.\n\n```python\nfrom guidance import system, user, assistant, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# System message\nwith system():\n    lm += \"You are a JSON generation expert.\"\n\n# User message\nwith user():\n    lm += \"Generate a person object with name and age.\"\n\n# Assistant response\nwith assistant():\n    lm += gen(\"response\", max_tokens=100)\n\nprint(lm[\"response\"])\n```\n\n**Benefits:**\n- Natural chat flow\n- Clear role separation\n- Easy to read and maintain\n\n### 2. Constrained Generation\n\nGuidance ensures outputs match specified patterns using regex or grammars.\n\n#### Regex Constraints\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Constrain to valid email format\nlm += \"Email: \" + gen(\"email\", regex=r\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}\")\n\n# Constrain to date format (YYYY-MM-DD)\nlm += \"Date: \" + gen(\"date\", regex=r\"\\d{4}-\\d{2}-\\d{2}\")\n\n# Constrain to phone number\nlm += \"Phone: \" + gen(\"phone\", regex=r\"\\d{3}-\\d{3}-\\d{4}\")\n\nprint(lm[\"email\"])  # Guaranteed valid email\nprint(lm[\"date\"])   # Guaranteed YYYY-MM-DD format\n```\n\n**How it works:**\n- Regex converted to grammar at token level\n- Invalid tokens filtered during generation\n- Model can only produce matching outputs\n\n#### Selection Constraints\n\n```python\nfrom guidance import models, gen, select\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Constrain to specific choices\nlm += \"Sentiment: \" + select([\"positive\", \"negative\", \"neutral\"], name=\"sentiment\")\n\n# Multiple-choice selection\nlm += \"Best answer: \" + select(\n    [\"A) Paris\", \"B) London\", \"C) Berlin\", \"D) Madrid\"],\n    name=\"answer\"\n)\n\nprint(lm[\"sentiment\"])  # One of: positive, negative, neutral\nprint(lm[\"answer\"])     # One of: A, B, C, or D\n```\n\n### 3. Token Healing\n\nGuidance automatically \"heals\" token boundaries between prompt and generation.\n\n**Problem:** Tokenization creates unnatural boundaries.\n\n```python\n# Without token healing\nprompt = \"The capital of France is \"\n# Last token: \" is \"\n# First generated token might be \" Par\" (with leading space)\n# Result: \"The capital of France is  Paris\" (double space!)\n```\n\n**Solution:** Guidance backs up one token and regenerates.\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Token healing enabled by default\nlm += \"The capital of France is \" + gen(\"capital\", max_tokens=5)\n# Result: \"The capital of France is Paris\" (correct spacing)\n```\n\n**Benefits:**\n- Natural text boundaries\n- No awkward spacing issues\n- Better model performance (sees natural token sequences)\n\n### 4. Grammar-Based Generation\n\nDefine complex structures using context-free grammars.\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# JSON grammar (simplified)\njson_grammar = \"\"\"\n{\n    \"name\": \u003Cgen name regex=\"[A-Za-z ]+\" max_tokens=20>,\n    \"age\": \u003Cgen age regex=\"[0-9]+\" max_tokens=3>,\n    \"email\": \u003Cgen email regex=\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}\" max_tokens=50>\n}\n\"\"\"\n\n# Generate valid JSON\nlm += gen(\"person\", grammar=json_grammar)\n\nprint(lm[\"person\"])  # Guaranteed valid JSON structure\n```\n\n**Use cases:**\n- Complex structured outputs\n- Nested data structures\n- Programming language syntax\n- Domain-specific languages\n\n### 5. Guidance Functions\n\nCreate reusable generation patterns with the `@guidance` decorator.\n\n```python\nfrom guidance import guidance, gen, models\n\n@guidance\ndef generate_person(lm):\n    \"\"\"Generate a person with name and age.\"\"\"\n    lm += \"Name: \" + gen(\"name\", max_tokens=20, stop=\"\\n\")\n    lm += \"\\nAge: \" + gen(\"age\", regex=r\"[0-9]+\", max_tokens=3)\n    return lm\n\n# Use the function\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\nlm = generate_person(lm)\n\nprint(lm[\"name\"])\nprint(lm[\"age\"])\n```\n\n**Stateful Functions:**\n\n```python\n@guidance(stateless=False)\ndef react_agent(lm, question, tools, max_rounds=5):\n    \"\"\"ReAct agent with tool use.\"\"\"\n    lm += f\"Question: {question}\\n\\n\"\n\n    for i in range(max_rounds):\n        # Thought\n        lm += f\"Thought {i+1}: \" + gen(\"thought\", stop=\"\\n\")\n\n        # Action\n        lm += \"\\nAction: \" + select(list(tools.keys()), name=\"action\")\n\n        # Execute tool\n        tool_result = tools[lm[\"action\"]]()\n        lm += f\"\\nObservation: {tool_result}\\n\\n\"\n\n        # Check if done\n        lm += \"Done? \" + select([\"Yes\", \"No\"], name=\"done\")\n        if lm[\"done\"] == \"Yes\":\n            break\n\n    # Final answer\n    lm += \"\\nFinal Answer: \" + gen(\"answer\", max_tokens=100)\n    return lm\n```\n\n## Backend Configuration\n\n### Anthropic Claude\n\n```python\nfrom guidance import models\n\nlm = models.Anthropic(\n    model=\"claude-sonnet-4-5-20250929\",\n    api_key=\"your-api-key\"  # Or set ANTHROPIC_API_KEY env var\n)\n```\n\n### OpenAI\n\n```python\nlm = models.OpenAI(\n    model=\"gpt-4o-mini\",\n    api_key=\"your-api-key\"  # Or set OPENAI_API_KEY env var\n)\n```\n\n### Local Models (Transformers)\n\n```python\nfrom guidance.models import Transformers\n\nlm = Transformers(\n    \"microsoft\u002FPhi-4-mini-instruct\",\n    device=\"cuda\"  # Or \"cpu\"\n)\n```\n\n### Local Models (llama.cpp)\n\n```python\nfrom guidance.models import LlamaCpp\n\nlm = LlamaCpp(\n    model_path=\"\u002Fpath\u002Fto\u002Fmodel.gguf\",\n    n_ctx=4096,\n    n_gpu_layers=35\n)\n```\n\n## Common Patterns\n\nDetails, code examples and parameter tables: [references\u002Fcommon-patterns.md](references\u002Fcommon-patterns.md). Read it when this step applies.\n\n## Best Practices\n\n### 1. Use Regex for Format Validation\n\n```python\n# ✅ Good: Regex ensures valid format\nlm += \"Email: \" + gen(\"email\", regex=r\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}\")\n\n# ❌ Bad: Free generation may produce invalid emails\nlm += \"Email: \" + gen(\"email\", max_tokens=50)\n```\n\n### 2. Use select() for Fixed Categories\n\n```python\n# ✅ Good: Guaranteed valid category\nlm += \"Status: \" + select([\"pending\", \"approved\", \"rejected\"], name=\"status\")\n\n# ❌ Bad: May generate typos or invalid values\nlm += \"Status: \" + gen(\"status\", max_tokens=20)\n```\n\n### 3. Leverage Token Healing\n\n```python\n# Token healing is enabled by default\n# No special action needed - just concatenate naturally\nlm += \"The capital is \" + gen(\"capital\")  # Automatic healing\n```\n\n### 4. Use stop Sequences\n\n```python\n# ✅ Good: Stop at newline for single-line outputs\nlm += \"Name: \" + gen(\"name\", stop=\"\\n\")\n\n# ❌ Bad: May generate multiple lines\nlm += \"Name: \" + gen(\"name\", max_tokens=50)\n```\n\n### 5. Create Reusable Functions\n\n```python\n# ✅ Good: Reusable pattern\n@guidance\ndef generate_person(lm):\n    lm += \"Name: \" + gen(\"name\", stop=\"\\n\")\n    lm += \"\\nAge: \" + gen(\"age\", regex=r\"[0-9]+\")\n    return lm\n\n# Use multiple times\nlm = generate_person(lm)\nlm += \"\\n\\n\"\nlm = generate_person(lm)\n```\n\n### 6. Balance Constraints\n\n```python\n# ✅ Good: Reasonable constraints\nlm += gen(\"name\", regex=r\"[A-Za-z ]+\", max_tokens=30)\n\n# ❌ Too strict: May fail or be very slow\nlm += gen(\"name\", regex=r\"^(John|Jane)$\", max_tokens=10)\n```\n\n## Comparison to Alternatives\n\n| Feature | Guidance | Instructor | Outlines | LMQL |\n|---------|----------|------------|----------|------|\n| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |\n| Grammar Support | ✅ CFG | ❌ No | ✅ CFG | ✅ CFG |\n| Pydantic Validation | ❌ No | ✅ Yes | ✅ Yes | ❌ No |\n| Token Healing | ✅ Yes | ❌ No | ✅ Yes | ❌ No |\n| Local Models | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |\n| API Models | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |\n| Pythonic Syntax | ✅ Yes | ✅ Yes | ✅ Yes | ❌ SQL-like |\n| Learning Curve | Low | Low | Medium | High |\n\n**When to choose Guidance:**\n- Need regex\u002Fgrammar constraints\n- Want token healing\n- Building complex workflows with control flow\n- Using local models (Transformers, llama.cpp)\n- Prefer Pythonic syntax\n\n**When to choose alternatives:**\n- Instructor: Need Pydantic validation with automatic retrying\n- Outlines: Need JSON schema validation\n- LMQL: Prefer declarative query syntax\n\n## Performance Characteristics\n\n**Latency Reduction:**\n- 30-50% faster than traditional prompting for constrained outputs\n- Token healing reduces unnecessary regeneration\n- Grammar constraints prevent invalid token generation\n\n**Memory Usage:**\n- Minimal overhead vs unconstrained generation\n- Grammar compilation cached after first use\n- Efficient token filtering at inference time\n\n**Token Efficiency:**\n- Prevents wasted tokens on invalid outputs\n- No need for retry loops\n- Direct path to valid outputs\n\n## Resources\n\n- **Documentation**: https:\u002F\u002Fguidance.readthedocs.io\n- **GitHub**: https:\u002F\u002Fgithub.com\u002Fguidance-ai\u002Fguidance\n- **Notebooks**: https:\u002F\u002Fgithub.com\u002Fguidance-ai\u002Fguidance\u002Ftree\u002Fmain\u002Fnotebooks\n- **Discord**: Community support available\n\n## See Also\n\n- `references\u002Fconstraints.md` - Comprehensive regex and grammar patterns\n- `references\u002Fbackends.md` - Backend-specific configuration\n- `references\u002Fexamples.md` - Production-ready examples\n\n## Agent operating procedure\n\n1. **Check the environment.** Confirm the framework version, model provider, API keys and rate limits.\n2. **Pin down the inputs.** Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.\n3. **Run a small version first.** Test a single call or chain with a known input and inspect raw outputs.\n4. **Execute the full task** using the instructions and references above.\n5. **Validate the result.** Evaluate on a small labeled set; check structured outputs against their schema; log prompts and responses.\n6. **Report.** State what was run (versions, commands, parameters), what was checked, and what is still uncertain.\n\n| If this happens | Do this |\n|---|---|\n| Outputs do not match the expected schema | Add validation and retries, tighten the schema, or simplify the prompt. |\n| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (`help()`, `--help`, official docs), adapt, and tell the user. Never invent an API. |\n| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |\n\n**Integrity rules**\n\n- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.\n- Never send private or sensitive data to external APIs without the user's consent.\n- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.\n- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.\n","# Guidance: Constrained LLM Generation\n\n## When to Use This Skill\n\nUse Guidance when you need to:\n- **Control LLM output syntax** with regex or grammars\n- **Guarantee valid JSON\u002FXML\u002Fcode** generation\n- **Reduce latency** vs traditional prompting approaches\n- **Enforce structured formats** (dates, emails, IDs, etc.)\n- **Build multi-step workflows** with Pythonic control flow\n- **Prevent invalid outputs** through grammatical constraints\n\n\n## Installation\n\n```bash\n# Base installation\npip install guidance\n\n# With specific backends\npip install guidance[transformers]  # Hugging Face models\npip install guidance[llama_cpp]     # llama.cpp models\n```\n\n## Quick Start\n\n### Basic Example: Structured Generation\n\n```python\nfrom guidance import models, gen\n\n# Load model (supports OpenAI, Transformers, llama.cpp)\nlm = models.OpenAI(\"gpt-4\")\n\n# Generate with constraints\nresult = lm + \"The capital of France is \" + gen(\"capital\", max_tokens=5)\n\nprint(result[\"capital\"])  # \"Paris\"\n```\n\n### With Anthropic Claude\n\n```python\nfrom guidance import models, gen, system, user, assistant\n\n# Configure Claude\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Use context managers for chat format\nwith system():\n    lm += \"You are a helpful assistant.\"\n\nwith user():\n    lm += \"What is the capital of France?\"\n\nwith assistant():\n    lm += gen(max_tokens=20)\n```\n\n## Core Concepts\n\n### 1. Context Managers\n\nGuidance uses Pythonic context managers for chat-style interactions.\n\n```python\nfrom guidance import system, user, assistant, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# System message\nwith system():\n    lm += \"You are a JSON generation expert.\"\n\n# User message\nwith user():\n    lm += \"Generate a person object with name and age.\"\n\n# Assistant response\nwith assistant():\n    lm += gen(\"response\", max_tokens=100)\n\nprint(lm[\"response\"])\n```\n\n**Benefits:**\n- Natural chat flow\n- Clear role separation\n- Easy to read and maintain\n\n### 2. Constrained Generation\n\nGuidance ensures outputs match specified patterns using regex or grammars.\n\n#### Regex Constraints\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Constrain to valid email format\nlm += \"Email: \" + gen(\"email\", regex=r\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}\")\n\n# Constrain to date format (YYYY-MM-DD)\nlm += \"Date: \" + gen(\"date\", regex=r\"\\d{4}-\\d{2}-\\d{2}\")\n\n# Constrain to phone number\nlm += \"Phone: \" + gen(\"phone\", regex=r\"\\d{3}-\\d{3}-\\d{4}\")\n\nprint(lm[\"email\"])  # Guaranteed valid email\nprint(lm[\"date\"])   # Guaranteed YYYY-MM-DD format\n```\n\n**How it works:**\n- Regex converted to grammar at token level\n- Invalid tokens filtered during generation\n- Model can only produce matching outputs\n\n#### Selection Constraints\n\n```python\nfrom guidance import models, gen, select\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Constrain to specific choices\nlm += \"Sentiment: \" + select([\"positive\", \"negative\", \"neutral\"], name=\"sentiment\")\n\n# Multiple-choice selection\nlm += \"Best answer: \" + select(\n    [\"A) Paris\", \"B) London\", \"C) Berlin\", \"D) Madrid\"],\n    name=\"answer\"\n)\n\nprint(lm[\"sentiment\"])  # One of: positive, negative, neutral\nprint(lm[\"answer\"])     # One of: A, B, C, or D\n```\n\n### 3. Token Healing\n\nGuidance automatically \"heals\" token boundaries between prompt and generation.\n\n**Problem:** Tokenization creates unnatural boundaries.\n\n```python\n# Without token healing\nprompt = \"The capital of France is \"\n# Last token: \" is \"\n# First generated token might be \" Par\" (with leading space)\n# Result: \"The capital of France is  Paris\" (double space!)\n```\n\n**Solution:** Guidance backs up one token and regenerates.\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# Token healing enabled by default\nlm += \"The capital of France is \" + gen(\"capital\", max_tokens=5)\n# Result: \"The capital of France is Paris\" (correct spacing)\n```\n\n**Benefits:**\n- Natural text boundaries\n- No awkward spacing issues\n- Better model performance (sees natural token sequences)\n\n### 4. Grammar-Based Generation\n\nDefine complex structures using context-free grammars.\n\n```python\nfrom guidance import models, gen\n\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\n\n# JSON grammar (simplified)\njson_grammar = \"\"\"\n{\n    \"name\": \u003Cgen name regex=\"[A-Za-z ]+\" max_tokens=20>,\n    \"age\": \u003Cgen age regex=\"[0-9]+\" max_tokens=3>,\n    \"email\": \u003Cgen email regex=\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}\" max_tokens=50>\n}\n\"\"\"\n\n# Generate valid JSON\nlm += gen(\"person\", grammar=json_grammar)\n\nprint(lm[\"person\"])  # Guaranteed valid JSON structure\n```\n\n**Use cases:**\n- Complex structured outputs\n- Nested data structures\n- Programming language syntax\n- Domain-specific languages\n\n### 5. Guidance Functions\n\nCreate reusable generation patterns with the `@guidance` decorator.\n\n```python\nfrom guidance import guidance, gen, models\n\n@guidance\ndef generate_person(lm):\n    \"\"\"Generate a person with name and age.\"\"\"\n    lm += \"Name: \" + gen(\"name\", max_tokens=20, stop=\"\\n\")\n    lm += \"\\nAge: \" + gen(\"age\", regex=r\"[0-9]+\", max_tokens=3)\n    return lm\n\n# Use the function\nlm = models.Anthropic(\"claude-sonnet-4-5-20250929\")\nlm = generate_person(lm)\n\nprint(lm[\"name\"])\nprint(lm[\"age\"])\n```\n\n**Stateful Functions:**\n\n```python\n@guidance(stateless=False)\ndef react_agent(lm, question, tools, max_rounds=5):\n    \"\"\"ReAct agent with tool use.\"\"\"\n    lm += f\"Question: {question}\\n\\n\"\n\n    for i in range(max_rounds):\n        # Thought\n        lm += f\"Thought {i+1}: \" + gen(\"thought\", stop=\"\\n\")\n\n        # Action\n        lm += \"\\nAction: \" + select(list(tools.keys()), name=\"action\")\n\n        # Execute tool\n        tool_result = tools[lm[\"action\"]]()\n        lm += f\"\\nObservation: {tool_result}\\n\\n\"\n\n        # Check if done\n        lm += \"Done? \" + select([\"Yes\", \"No\"], name=\"done\")\n        if lm[\"done\"] == \"Yes\":\n            break\n\n    # Final answer\n    lm += \"\\nFinal Answer: \" + gen(\"answer\", max_tokens=100)\n    return lm\n```\n\n## Backend Configuration\n\n### Anthropic Claude\n\n```python\nfrom guidance import models\n\nlm = models.Anthropic(\n    model=\"claude-sonnet-4-5-20250929\",\n    api_key=\"your-api-key\"  # Or set ANTHROPIC_API_KEY env var\n)\n```\n\n### OpenAI\n\n```python\nlm = models.OpenAI(\n    model=\"gpt-4o-mini\",\n    api_key=\"your-api-key\"  # Or set OPENAI_API_KEY env var\n)\n```\n\n### Local Models (Transformers)\n\n```python\nfrom guidance.models import Transformers\n\nlm = Transformers(\n    \"microsoft\u002FPhi-4-mini-instruct\",\n    device=\"cuda\"  # Or \"cpu\"\n)\n```\n\n### Local Models (llama.cpp)\n\n```python\nfrom guidance.models import LlamaCpp\n\nlm = LlamaCpp(\n    model_path=\"\u002Fpath\u002Fto\u002Fmodel.gguf\",\n    n_ctx=4096,\n    n_gpu_layers=35\n)\n```\n\n## Common Patterns\n\nDetails, code examples and parameter tables: [references\u002Fcommon-patterns.md](references\u002Fcommon-patterns.md). Read it when this step applies.\n\n## Best Practices\n\n### 1. Use Regex for Format Validation\n\n```python\n# ✅ Good: Regex ensures valid format\nlm += \"Email: \" + gen(\"email\", regex=r\"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}\")\n\n# ❌ Bad: Free generation may produce invalid emails\nlm += \"Email: \" + gen(\"email\", max_tokens=50)\n```\n\n### 2. Use select() for Fixed Categories\n\n```python\n# ✅ Good: Guaranteed valid category\nlm += \"Status: \" + select([\"pending\", \"approved\", \"rejected\"], name=\"status\")\n\n# ❌ Bad: May generate typos or invalid values\nlm += \"Status: \" + gen(\"status\", max_tokens=20)\n```\n\n### 3. Leverage Token Healing\n\n```python\n# Token healing is enabled by default\n# No special action needed - just concatenate naturally\nlm += \"The capital is \" + gen(\"capital\")  # Automatic healing\n```\n\n### 4. Use stop Sequences\n\n```python\n# ✅ Good: Stop at newline for single-line outputs\nlm += \"Name: \" + gen(\"name\", stop=\"\\n\")\n\n# ❌ Bad: May generate multiple lines\nlm += \"Name: \" + gen(\"name\", max_tokens=50)\n```\n\n### 5. Create Reusable Functions\n\n```python\n# ✅ Good: Reusable pattern\n@guidance\ndef generate_person(lm):\n    lm += \"Name: \" + gen(\"name\", stop=\"\\n\")\n    lm += \"\\nAge: \" + gen(\"age\", regex=r\"[0-9]+\")\n    return lm\n\n# Use multiple times\nlm = generate_person(lm)\nlm += \"\\n\\n\"\nlm = generate_person(lm)\n```\n\n### 6. Balance Constraints\n\n```python\n# ✅ Good: Reasonable constraints\nlm += gen(\"name\", regex=r\"[A-Za-z ]+\", max_tokens=30)\n\n# ❌ Too strict: May fail or be very slow\nlm += gen(\"name\", regex=r\"^(John|Jane)$\", max_tokens=10)\n```\n\n## Comparison to Alternatives\n\n| Feature | Guidance | Instructor | Outlines | LMQL |\n|---------|----------|------------|----------|------|\n| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |\n| Grammar Support | ✅ CFG | ❌ No | ✅ CFG | ✅ CFG |\n| Pydantic Validation | ❌ No | ✅ Yes | ✅ Yes | ❌ No |\n| Token Healing | ✅ Yes | ❌ No | ✅ Yes | ❌ No |\n| Local Models | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |\n| API Models | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |\n| Pythonic Syntax | ✅ Yes | ✅ Yes | ✅ Yes | ❌ SQL-like |\n| Learning Curve | Low | Low | Medium | High |\n\n**When to choose Guidance:**\n- Need regex\u002Fgrammar constraints\n- Want token healing\n- Building complex workflows with control flow\n- Using local models (Transformers, llama.cpp)\n- Prefer Pythonic syntax\n\n**When to choose alternatives:**\n- Instructor: Need Pydantic validation with automatic retrying\n- Outlines: Need JSON schema validation\n- LMQL: Prefer declarative query syntax\n\n## Performance Characteristics\n\n**Latency Reduction:**\n- 30-50% faster than traditional prompting for constrained outputs\n- Token healing reduces unnecessary regeneration\n- Grammar constraints prevent invalid token generation\n\n**Memory Usage:**\n- Minimal overhead vs unconstrained generation\n- Grammar compilation cached after first use\n- Efficient token filtering at inference time\n\n**Token Efficiency:**\n- Prevents wasted tokens on invalid outputs\n- No need for retry loops\n- Direct path to valid outputs\n\n## Resources\n\n- **Documentation**: https:\u002F\u002Fguidance.readthedocs.io\n- **GitHub**: https:\u002F\u002Fgithub.com\u002Fguidance-ai\u002Fguidance\n- **Notebooks**: https:\u002F\u002Fgithub.com\u002Fguidance-ai\u002Fguidance\u002Ftree\u002Fmain\u002Fnotebooks\n- **Discord**: Community support available\n\n## See Also\n\n- `references\u002Fconstraints.md` - Comprehensive regex and grammar patterns\n- `references\u002Fbackends.md` - Backend-specific configuration\n- `references\u002Fexamples.md` - Production-ready examples\n\n## Agent operating procedure\n\n1. **Check the environment.** Confirm the framework version, model provider, API keys and rate limits.\n2. **Pin down the inputs.** Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.\n3. **Run a small version first.** Test a single call or chain with a known input and inspect raw outputs.\n4. **Execute the full task** using the instructions and references above.\n5. **Validate the result.** Evaluate on a small labeled set; check structured outputs against their schema; log prompts and responses.\n6. **Report.** State what was run (versions, commands, parameters), what was checked, and what is still uncertain.\n\n| If this happens | Do this |\n|---|---|\n| Outputs do not match the expected schema | Add validation and retries, tighten the schema, or simplify the prompt. |\n| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (`help()`, `--help`, official docs), adapt, and tell the user. Never invent an API. |\n| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |\n\n**Integrity rules**\n\n- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.\n- Never send private or sensitive data to external APIs without the user's consent.\n- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.\n- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.\n",{"name":5,"license":15,"metadata":51,"description":7},{"tags":52,"version":53,"category":54,"maintainer":55,"dependencies":56},"Prompt Engineering, Guidance, Constrained Generation, Structured Output, JSON Validation, Grammar, Microsoft Research, Format Enforcement, Multi-Step Workflows","1.0.0","llm-applications","Kalaris Labs","guidance, transformers","main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":79},[69,72,75],{"tool":70,"command":71},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill guidance",{"tool":73,"command":74},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill guidance",{"tool":76,"command":77},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill guidance","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002FSKILL.md",true,[81,87,91,95,99],{"path":82,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Fbackends.md","REFERENCE","参考文档",12010,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002Freferences\u002Fbackends.md",{"path":88,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Fcommon-patterns.md",3770,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002Freferences\u002Fcommon-patterns.md",{"path":92,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Fconstraints.md",15886,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002Freferences\u002Fconstraints.md",{"path":96,"resourceType":83,"resourceTypeDesc":84,"sizeBytes":97,"sourceHtmlUrl":98},"references\u002Fexamples.md",20111,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002Freferences\u002Fexamples.md",{"path":100,"resourceType":101,"resourceTypeDesc":102,"sizeBytes":103,"sourceHtmlUrl":104},"scripts\u002Fsafe_arithmetic.py","SCRIPT","脚本",1295,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FKalarisLabs\u002Fresearch-agent-skills\u002Fskills\u002Fguidance\u002Fscripts\u002Fsafe_arithmetic.py",[106,115,123,131,139,147],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":110,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":114},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":119,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":114},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":124,"name":125,"nameZh":6,"description":126,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":127,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":114},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":135,"sourceHtmlUrl":136,"categories":137,"keywords":138,"publishedAt":114},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":143,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":114},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":151,"sourceHtmlUrl":152,"categories":153,"keywords":154,"publishedAt":114},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]