[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78E5FPRH6CFN90T92W5JS92":3,"skill-same:01M78E5FPRH6CFN90T92W5JS92":79},{"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":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":14,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":48,"ownerDescription":49,"updatedAt":50,"install":51,"resources":64},"01M78E5FPRH6CFN90T92W5JS92","outlines",null,"Outlines: structured JSON\u002Fregex\u002FPydantic LLM generation.","pvbang\u002Fnexus","pvbang","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F89725712?v=4","01M78B6R1DXZZBTN9G0XXBBE0A","Phan Văn Bằng","01M78B6R2T4DYQ9ZY4GJR0Q3V4",0,"MIT","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: outlines\ndescription: \"Outlines: structured JSON\u002Fregex\u002FPydantic LLM generation.\"\nversion: 1.0.0\nauthor: Orchestra Research\nlicense: MIT\ndependencies: [outlines, transformers, vllm, pydantic]\nmetadata:\n  hermes:\n    tags: [Prompt Engineering, Outlines, Structured Generation, JSON Schema, Pydantic, Local Models, Grammar-Based Generation, vLLM, Transformers, Type Safety]\n\n---\n\n# Outlines: Structured Text Generation\n\n## When to Use This Skill\n\nUse Outlines when you need to:\n- **Guarantee valid JSON\u002FXML\u002Fcode** structure during generation\n- **Use Pydantic models** for type-safe outputs\n- **Support local models** (Transformers, llama.cpp, vLLM)\n- **Maximize inference speed** with zero-overhead structured generation\n- **Generate against JSON schemas** automatically\n- **Control token sampling** at the grammar level\n\n**GitHub Stars**: 8,000+ | **From**: dottxt.ai (formerly .txt)\n\n## Installation\n\n```bash\n# Base installation\npip install outlines\n\n# With specific backends\npip install outlines transformers  # Hugging Face models\npip install outlines llama-cpp-python  # llama.cpp\npip install outlines vllm  # vLLM for high-throughput\n```\n\n## Quick Start\n\n### Basic Example: Classification\n\n```python\nimport outlines\nfrom typing import Literal\n\n# Load model\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Generate with type constraint\nprompt = \"Sentiment of 'This product is amazing!': \"\ngenerator = outlines.generate.choice(model, [\"positive\", \"negative\", \"neutral\"])\nsentiment = generator(prompt)\n\nprint(sentiment)  # \"positive\" (guaranteed one of these)\n```\n\n### With Pydantic Models\n\n```python\nfrom pydantic import BaseModel\nimport outlines\n\nclass User(BaseModel):\n    name: str\n    age: int\n    email: str\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Generate structured output\nprompt = \"Extract user: John Doe, 30 years old, john@example.com\"\ngenerator = outlines.generate.json(model, User)\nuser = generator(prompt)\n\nprint(user.name)   # \"John Doe\"\nprint(user.age)    # 30\nprint(user.email)  # \"john@example.com\"\n```\n\n## Core Concepts\n\n### 1. Constrained Token Sampling\n\nOutlines uses Finite State Machines (FSM) to constrain token generation at the logit level.\n\n**How it works:**\n1. Convert schema (JSON\u002FPydantic\u002Fregex) to context-free grammar (CFG)\n2. Transform CFG into Finite State Machine (FSM)\n3. Filter invalid tokens at each step during generation\n4. Fast-forward when only one valid token exists\n\n**Benefits:**\n- **Zero overhead**: Filtering happens at token level\n- **Speed improvement**: Fast-forward through deterministic paths\n- **Guaranteed validity**: Invalid outputs impossible\n\n```python\nimport outlines\n\n# Pydantic model -> JSON schema -> CFG -> FSM\nclass Person(BaseModel):\n    name: str\n    age: int\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Behind the scenes:\n# 1. Person -> JSON schema\n# 2. JSON schema -> CFG\n# 3. CFG -> FSM\n# 4. FSM filters tokens during generation\n\ngenerator = outlines.generate.json(model, Person)\nresult = generator(\"Generate person: Alice, 25\")\n```\n\n### 2. Structured Generators\n\nOutlines provides specialized generators for different output types.\n\n#### Choice Generator\n\n```python\n# Multiple choice selection\ngenerator = outlines.generate.choice(\n    model,\n    [\"positive\", \"negative\", \"neutral\"]\n)\n\nsentiment = generator(\"Review: This is great!\")\n# Result: One of the three choices\n```\n\n#### JSON Generator\n\n```python\nfrom pydantic import BaseModel\n\nclass Product(BaseModel):\n    name: str\n    price: float\n    in_stock: bool\n\n# Generate valid JSON matching schema\ngenerator = outlines.generate.json(model, Product)\nproduct = generator(\"Extract: iPhone 15, $999, available\")\n\n# Guaranteed valid Product instance\nprint(type(product))  # \u003Cclass '__main__.Product'>\n```\n\n#### Regex Generator\n\n```python\n# Generate text matching regex\ngenerator = outlines.generate.regex(\n    model,\n    r\"[0-9]{3}-[0-9]{3}-[0-9]{4}\"  # Phone number pattern\n)\n\nphone = generator(\"Generate phone number:\")\n# Result: \"555-123-4567\" (guaranteed to match pattern)\n```\n\n#### Integer\u002FFloat Generators\n\n```python\n# Generate specific numeric types\nint_generator = outlines.generate.integer(model)\nage = int_generator(\"Person's age:\")  # Guaranteed integer\n\nfloat_generator = outlines.generate.float(model)\nprice = float_generator(\"Product price:\")  # Guaranteed float\n```\n\n### 3. Model Backends\n\nOutlines supports multiple local and API-based backends.\n\n#### Transformers (Hugging Face)\n\n```python\nimport outlines\n\n# Load from Hugging Face\nmodel = outlines.models.transformers(\n    \"microsoft\u002FPhi-3-mini-4k-instruct\",\n    device=\"cuda\"  # Or \"cpu\"\n)\n\n# Use with any generator\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### llama.cpp\n\n```python\n# Load GGUF model\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fllama-3.1-8b-instruct.Q4_K_M.gguf\",\n    n_gpu_layers=35\n)\n\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### vLLM (High Throughput)\n\n```python\n# For production deployments\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-8B-Instruct\",\n    tensor_parallel_size=2  # Multi-GPU\n)\n\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### OpenAI (Limited Support)\n\n```python\n# Basic OpenAI support\nmodel = outlines.models.openai(\n    \"gpt-4o-mini\",\n    api_key=\"your-api-key\"\n)\n\n# Note: Some features limited with API models\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n### 4. Pydantic Integration\n\nOutlines has first-class Pydantic support with automatic schema translation.\n\n#### Basic Models\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass Article(BaseModel):\n    title: str = Field(description=\"Article title\")\n    author: str = Field(description=\"Author name\")\n    word_count: int = Field(description=\"Number of words\", gt=0)\n    tags: list[str] = Field(description=\"List of tags\")\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, Article)\n\narticle = generator(\"Generate article about AI\")\nprint(article.title)\nprint(article.word_count)  # Guaranteed > 0\n```\n\n#### Nested Models\n\n```python\nclass Address(BaseModel):\n    street: str\n    city: str\n    country: str\n\nclass Person(BaseModel):\n    name: str\n    age: int\n    address: Address  # Nested model\n\ngenerator = outlines.generate.json(model, Person)\nperson = generator(\"Generate person in New York\")\n\nprint(person.address.city)  # \"New York\"\n```\n\n#### Enums and Literals\n\n```python\nfrom enum import Enum\nfrom typing import Literal\n\nclass Status(str, Enum):\n    PENDING = \"pending\"\n    APPROVED = \"approved\"\n    REJECTED = \"rejected\"\n\nclass Application(BaseModel):\n    applicant: str\n    status: Status  # Must be one of enum values\n    priority: Literal[\"low\", \"medium\", \"high\"]  # Must be one of literals\n\ngenerator = outlines.generate.json(model, Application)\napp = generator(\"Generate application\")\n\nprint(app.status)  # Status.PENDING (or APPROVED\u002FREJECTED)\n```\n\n## Common Patterns\n\n### Pattern 1: Data Extraction\n\n```python\nfrom pydantic import BaseModel\nimport outlines\n\nclass CompanyInfo(BaseModel):\n    name: str\n    founded_year: int\n    industry: str\n    employees: int\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, CompanyInfo)\n\ntext = \"\"\"\nApple Inc. was founded in 1976 in the technology industry.\nThe company employs approximately 164,000 people worldwide.\n\"\"\"\n\nprompt = f\"Extract company information:\\n{text}\\n\\nCompany:\"\ncompany = generator(prompt)\n\nprint(f\"Name: {company.name}\")\nprint(f\"Founded: {company.founded_year}\")\nprint(f\"Industry: {company.industry}\")\nprint(f\"Employees: {company.employees}\")\n```\n\n### Pattern 2: Classification\n\n```python\nfrom typing import Literal\nimport outlines\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Binary classification\ngenerator = outlines.generate.choice(model, [\"spam\", \"not_spam\"])\nresult = generator(\"Email: Buy now! 50% off!\")\n\n# Multi-class classification\ncategories = [\"technology\", \"business\", \"sports\", \"entertainment\"]\ncategory_gen = outlines.generate.choice(model, categories)\ncategory = category_gen(\"Article: Apple announces new iPhone...\")\n\n# With confidence\nclass Classification(BaseModel):\n    label: Literal[\"positive\", \"negative\", \"neutral\"]\n    confidence: float\n\nclassifier = outlines.generate.json(model, Classification)\nresult = classifier(\"Review: This product is okay, nothing special\")\n```\n\n### Pattern 3: Structured Forms\n\n```python\nclass UserProfile(BaseModel):\n    full_name: str\n    age: int\n    email: str\n    phone: str\n    country: str\n    interests: list[str]\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, UserProfile)\n\nprompt = \"\"\"\nExtract user profile from:\nName: Alice Johnson\nAge: 28\nEmail: alice@example.com\nPhone: 555-0123\nCountry: USA\nInterests: hiking, photography, cooking\n\"\"\"\n\nprofile = generator(prompt)\nprint(profile.full_name)\nprint(profile.interests)  # [\"hiking\", \"photography\", \"cooking\"]\n```\n\n### Pattern 4: Multi-Entity Extraction\n\n```python\nclass Entity(BaseModel):\n    name: str\n    type: Literal[\"PERSON\", \"ORGANIZATION\", \"LOCATION\"]\n\nclass DocumentEntities(BaseModel):\n    entities: list[Entity]\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, DocumentEntities)\n\ntext = \"Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond.\"\nprompt = f\"Extract entities from: {text}\"\n\nresult = generator(prompt)\nfor entity in result.entities:\n    print(f\"{entity.name} ({entity.type})\")\n```\n\n### Pattern 5: Code Generation\n\n```python\nclass PythonFunction(BaseModel):\n    function_name: str\n    parameters: list[str]\n    docstring: str\n    body: str\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, PythonFunction)\n\nprompt = \"Generate a Python function to calculate factorial\"\nfunc = generator(prompt)\n\nprint(f\"def {func.function_name}({', '.join(func.parameters)}):\")\nprint(f'    \"\"\"{func.docstring}\"\"\"')\nprint(f\"    {func.body}\")\n```\n\n### Pattern 6: Batch Processing\n\n```python\ndef batch_extract(texts: list[str], schema: type[BaseModel]):\n    \"\"\"Extract structured data from multiple texts.\"\"\"\n    model = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n    generator = outlines.generate.json(model, schema)\n\n    results = []\n    for text in texts:\n        result = generator(f\"Extract from: {text}\")\n        results.append(result)\n\n    return results\n\nclass Person(BaseModel):\n    name: str\n    age: int\n\ntexts = [\n    \"John is 30 years old\",\n    \"Alice is 25 years old\",\n    \"Bob is 40 years old\"\n]\n\npeople = batch_extract(texts, Person)\nfor person in people:\n    print(f\"{person.name}: {person.age}\")\n```\n\n## Backend Configuration\n\n### Transformers\n\n```python\nimport outlines\n\n# Basic usage\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# GPU configuration\nmodel = outlines.models.transformers(\n    \"microsoft\u002FPhi-3-mini-4k-instruct\",\n    device=\"cuda\",\n    model_kwargs={\"torch_dtype\": \"float16\"}\n)\n\n# Popular models\nmodel = outlines.models.transformers(\"meta-llama\u002FLlama-3.1-8B-Instruct\")\nmodel = outlines.models.transformers(\"mistralai\u002FMistral-7B-Instruct-v0.3\")\nmodel = outlines.models.transformers(\"Qwen\u002FQwen2.5-7B-Instruct\")\n```\n\n### llama.cpp\n\n```python\n# Load GGUF model\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fllama-3.1-8b.Q4_K_M.gguf\",\n    n_ctx=4096,         # Context window\n    n_gpu_layers=35,    # GPU layers\n    n_threads=8         # CPU threads\n)\n\n# Full GPU offload\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fmodel.gguf\",\n    n_gpu_layers=-1  # All layers on GPU\n)\n```\n\n### vLLM (Production)\n\n```python\n# Single GPU\nmodel = outlines.models.vllm(\"meta-llama\u002FLlama-3.1-8B-Instruct\")\n\n# Multi-GPU\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-70B-Instruct\",\n    tensor_parallel_size=4  # 4 GPUs\n)\n\n# With quantization\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-8B-Instruct\",\n    quantization=\"awq\"  # Or \"gptq\"\n)\n```\n\n## Best Practices\n\n### 1. Use Specific Types\n\n```python\n# ✅ Good: Specific types\nclass Product(BaseModel):\n    name: str\n    price: float  # Not str\n    quantity: int  # Not str\n    in_stock: bool  # Not str\n\n# ❌ Bad: Everything as string\nclass Product(BaseModel):\n    name: str\n    price: str  # Should be float\n    quantity: str  # Should be int\n```\n\n### 2. Add Constraints\n\n```python\nfrom pydantic import Field\n\n# ✅ Good: With constraints\nclass User(BaseModel):\n    name: str = Field(min_length=1, max_length=100)\n    age: int = Field(ge=0, le=120)\n    email: str = Field(pattern=r\"^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$\")\n\n# ❌ Bad: No constraints\nclass User(BaseModel):\n    name: str\n    age: int\n    email: str\n```\n\n### 3. Use Enums for Categories\n\n```python\n# ✅ Good: Enum for fixed set\nclass Priority(str, Enum):\n    LOW = \"low\"\n    MEDIUM = \"medium\"\n    HIGH = \"high\"\n\nclass Task(BaseModel):\n    title: str\n    priority: Priority\n\n# ❌ Bad: Free-form string\nclass Task(BaseModel):\n    title: str\n    priority: str  # Can be anything\n```\n\n### 4. Provide Context in Prompts\n\n```python\n# ✅ Good: Clear context\nprompt = \"\"\"\nExtract product information from the following text.\nText: iPhone 15 Pro costs $999 and is currently in stock.\nProduct:\n\"\"\"\n\n# ❌ Bad: Minimal context\nprompt = \"iPhone 15 Pro costs $999 and is currently in stock.\"\n```\n\n### 5. Handle Optional Fields\n\n```python\nfrom typing import Optional\n\n# ✅ Good: Optional fields for incomplete data\nclass Article(BaseModel):\n    title: str  # Required\n    author: Optional[str] = None  # Optional\n    date: Optional[str] = None  # Optional\n    tags: list[str] = []  # Default empty list\n\n# Can succeed even if author\u002Fdate missing\n```\n\n## Comparison to Alternatives\n\n| Feature | Outlines | Instructor | Guidance | LMQL |\n|---------|----------|------------|----------|------|\n| Pydantic Support | ✅ Native | ✅ Native | ❌ No | ❌ No |\n| JSON Schema | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |\n| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |\n| Local Models | ✅ Full | ⚠️ Limited | ✅ Full | ✅ Full |\n| API Models | ⚠️ Limited | ✅ Full | ✅ Full | ✅ Full |\n| Zero Overhead | ✅ Yes | ❌ No | ⚠️ Partial | ✅ Yes |\n| Automatic Retrying | ❌ No | ✅ Yes | ❌ No | ❌ No |\n| Learning Curve | Low | Low | Low | High |\n\n**When to choose Outlines:**\n- Using local models (Transformers, llama.cpp, vLLM)\n- Need maximum inference speed\n- Want Pydantic model support\n- Require zero-overhead structured generation\n- Control token sampling process\n\n**When to choose alternatives:**\n- Instructor: Need API models with automatic retrying\n- Guidance: Need token healing and complex workflows\n- LMQL: Prefer declarative query syntax\n\n## Performance Characteristics\n\n**Speed:**\n- **Zero overhead**: Structured generation as fast as unconstrained\n- **Fast-forward optimization**: Skips deterministic tokens\n- **1.2-2x faster** than post-generation validation approaches\n\n**Memory:**\n- FSM compiled once per schema (cached)\n- Minimal runtime overhead\n- Efficient with vLLM for high throughput\n\n**Accuracy:**\n- **100% valid outputs** (guaranteed by FSM)\n- No retry loops needed\n- Deterministic token filtering\n\n## Resources\n\n- **Documentation**: https:\u002F\u002Foutlines-dev.github.io\u002Foutlines\n- **GitHub**: https:\u002F\u002Fgithub.com\u002Foutlines-dev\u002Foutlines (8k+ stars)\n- **Discord**: https:\u002F\u002Fdiscord.gg\u002FR9DSu34mGd\n- **Blog**: https:\u002F\u002Fblog.dottxt.co\n\n## See Also\n\n- `references\u002Fjson_generation.md` - Comprehensive JSON and Pydantic patterns\n- `references\u002Fbackends.md` - Backend-specific configuration\n- `references\u002Fexamples.md` - Production-ready examples\n\n\n","# Outlines: Structured Text Generation\n\n## When to Use This Skill\n\nUse Outlines when you need to:\n- **Guarantee valid JSON\u002FXML\u002Fcode** structure during generation\n- **Use Pydantic models** for type-safe outputs\n- **Support local models** (Transformers, llama.cpp, vLLM)\n- **Maximize inference speed** with zero-overhead structured generation\n- **Generate against JSON schemas** automatically\n- **Control token sampling** at the grammar level\n\n**GitHub Stars**: 8,000+ | **From**: dottxt.ai (formerly .txt)\n\n## Installation\n\n```bash\n# Base installation\npip install outlines\n\n# With specific backends\npip install outlines transformers  # Hugging Face models\npip install outlines llama-cpp-python  # llama.cpp\npip install outlines vllm  # vLLM for high-throughput\n```\n\n## Quick Start\n\n### Basic Example: Classification\n\n```python\nimport outlines\nfrom typing import Literal\n\n# Load model\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Generate with type constraint\nprompt = \"Sentiment of 'This product is amazing!': \"\ngenerator = outlines.generate.choice(model, [\"positive\", \"negative\", \"neutral\"])\nsentiment = generator(prompt)\n\nprint(sentiment)  # \"positive\" (guaranteed one of these)\n```\n\n### With Pydantic Models\n\n```python\nfrom pydantic import BaseModel\nimport outlines\n\nclass User(BaseModel):\n    name: str\n    age: int\n    email: str\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Generate structured output\nprompt = \"Extract user: John Doe, 30 years old, john@example.com\"\ngenerator = outlines.generate.json(model, User)\nuser = generator(prompt)\n\nprint(user.name)   # \"John Doe\"\nprint(user.age)    # 30\nprint(user.email)  # \"john@example.com\"\n```\n\n## Core Concepts\n\n### 1. Constrained Token Sampling\n\nOutlines uses Finite State Machines (FSM) to constrain token generation at the logit level.\n\n**How it works:**\n1. Convert schema (JSON\u002FPydantic\u002Fregex) to context-free grammar (CFG)\n2. Transform CFG into Finite State Machine (FSM)\n3. Filter invalid tokens at each step during generation\n4. Fast-forward when only one valid token exists\n\n**Benefits:**\n- **Zero overhead**: Filtering happens at token level\n- **Speed improvement**: Fast-forward through deterministic paths\n- **Guaranteed validity**: Invalid outputs impossible\n\n```python\nimport outlines\n\n# Pydantic model -> JSON schema -> CFG -> FSM\nclass Person(BaseModel):\n    name: str\n    age: int\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Behind the scenes:\n# 1. Person -> JSON schema\n# 2. JSON schema -> CFG\n# 3. CFG -> FSM\n# 4. FSM filters tokens during generation\n\ngenerator = outlines.generate.json(model, Person)\nresult = generator(\"Generate person: Alice, 25\")\n```\n\n### 2. Structured Generators\n\nOutlines provides specialized generators for different output types.\n\n#### Choice Generator\n\n```python\n# Multiple choice selection\ngenerator = outlines.generate.choice(\n    model,\n    [\"positive\", \"negative\", \"neutral\"]\n)\n\nsentiment = generator(\"Review: This is great!\")\n# Result: One of the three choices\n```\n\n#### JSON Generator\n\n```python\nfrom pydantic import BaseModel\n\nclass Product(BaseModel):\n    name: str\n    price: float\n    in_stock: bool\n\n# Generate valid JSON matching schema\ngenerator = outlines.generate.json(model, Product)\nproduct = generator(\"Extract: iPhone 15, $999, available\")\n\n# Guaranteed valid Product instance\nprint(type(product))  # \u003Cclass '__main__.Product'>\n```\n\n#### Regex Generator\n\n```python\n# Generate text matching regex\ngenerator = outlines.generate.regex(\n    model,\n    r\"[0-9]{3}-[0-9]{3}-[0-9]{4}\"  # Phone number pattern\n)\n\nphone = generator(\"Generate phone number:\")\n# Result: \"555-123-4567\" (guaranteed to match pattern)\n```\n\n#### Integer\u002FFloat Generators\n\n```python\n# Generate specific numeric types\nint_generator = outlines.generate.integer(model)\nage = int_generator(\"Person's age:\")  # Guaranteed integer\n\nfloat_generator = outlines.generate.float(model)\nprice = float_generator(\"Product price:\")  # Guaranteed float\n```\n\n### 3. Model Backends\n\nOutlines supports multiple local and API-based backends.\n\n#### Transformers (Hugging Face)\n\n```python\nimport outlines\n\n# Load from Hugging Face\nmodel = outlines.models.transformers(\n    \"microsoft\u002FPhi-3-mini-4k-instruct\",\n    device=\"cuda\"  # Or \"cpu\"\n)\n\n# Use with any generator\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### llama.cpp\n\n```python\n# Load GGUF model\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fllama-3.1-8b-instruct.Q4_K_M.gguf\",\n    n_gpu_layers=35\n)\n\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### vLLM (High Throughput)\n\n```python\n# For production deployments\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-8B-Instruct\",\n    tensor_parallel_size=2  # Multi-GPU\n)\n\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n#### OpenAI (Limited Support)\n\n```python\n# Basic OpenAI support\nmodel = outlines.models.openai(\n    \"gpt-4o-mini\",\n    api_key=\"your-api-key\"\n)\n\n# Note: Some features limited with API models\ngenerator = outlines.generate.json(model, YourModel)\n```\n\n### 4. Pydantic Integration\n\nOutlines has first-class Pydantic support with automatic schema translation.\n\n#### Basic Models\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass Article(BaseModel):\n    title: str = Field(description=\"Article title\")\n    author: str = Field(description=\"Author name\")\n    word_count: int = Field(description=\"Number of words\", gt=0)\n    tags: list[str] = Field(description=\"List of tags\")\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, Article)\n\narticle = generator(\"Generate article about AI\")\nprint(article.title)\nprint(article.word_count)  # Guaranteed > 0\n```\n\n#### Nested Models\n\n```python\nclass Address(BaseModel):\n    street: str\n    city: str\n    country: str\n\nclass Person(BaseModel):\n    name: str\n    age: int\n    address: Address  # Nested model\n\ngenerator = outlines.generate.json(model, Person)\nperson = generator(\"Generate person in New York\")\n\nprint(person.address.city)  # \"New York\"\n```\n\n#### Enums and Literals\n\n```python\nfrom enum import Enum\nfrom typing import Literal\n\nclass Status(str, Enum):\n    PENDING = \"pending\"\n    APPROVED = \"approved\"\n    REJECTED = \"rejected\"\n\nclass Application(BaseModel):\n    applicant: str\n    status: Status  # Must be one of enum values\n    priority: Literal[\"low\", \"medium\", \"high\"]  # Must be one of literals\n\ngenerator = outlines.generate.json(model, Application)\napp = generator(\"Generate application\")\n\nprint(app.status)  # Status.PENDING (or APPROVED\u002FREJECTED)\n```\n\n## Common Patterns\n\n### Pattern 1: Data Extraction\n\n```python\nfrom pydantic import BaseModel\nimport outlines\n\nclass CompanyInfo(BaseModel):\n    name: str\n    founded_year: int\n    industry: str\n    employees: int\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, CompanyInfo)\n\ntext = \"\"\"\nApple Inc. was founded in 1976 in the technology industry.\nThe company employs approximately 164,000 people worldwide.\n\"\"\"\n\nprompt = f\"Extract company information:\\n{text}\\n\\nCompany:\"\ncompany = generator(prompt)\n\nprint(f\"Name: {company.name}\")\nprint(f\"Founded: {company.founded_year}\")\nprint(f\"Industry: {company.industry}\")\nprint(f\"Employees: {company.employees}\")\n```\n\n### Pattern 2: Classification\n\n```python\nfrom typing import Literal\nimport outlines\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# Binary classification\ngenerator = outlines.generate.choice(model, [\"spam\", \"not_spam\"])\nresult = generator(\"Email: Buy now! 50% off!\")\n\n# Multi-class classification\ncategories = [\"technology\", \"business\", \"sports\", \"entertainment\"]\ncategory_gen = outlines.generate.choice(model, categories)\ncategory = category_gen(\"Article: Apple announces new iPhone...\")\n\n# With confidence\nclass Classification(BaseModel):\n    label: Literal[\"positive\", \"negative\", \"neutral\"]\n    confidence: float\n\nclassifier = outlines.generate.json(model, Classification)\nresult = classifier(\"Review: This product is okay, nothing special\")\n```\n\n### Pattern 3: Structured Forms\n\n```python\nclass UserProfile(BaseModel):\n    full_name: str\n    age: int\n    email: str\n    phone: str\n    country: str\n    interests: list[str]\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, UserProfile)\n\nprompt = \"\"\"\nExtract user profile from:\nName: Alice Johnson\nAge: 28\nEmail: alice@example.com\nPhone: 555-0123\nCountry: USA\nInterests: hiking, photography, cooking\n\"\"\"\n\nprofile = generator(prompt)\nprint(profile.full_name)\nprint(profile.interests)  # [\"hiking\", \"photography\", \"cooking\"]\n```\n\n### Pattern 4: Multi-Entity Extraction\n\n```python\nclass Entity(BaseModel):\n    name: str\n    type: Literal[\"PERSON\", \"ORGANIZATION\", \"LOCATION\"]\n\nclass DocumentEntities(BaseModel):\n    entities: list[Entity]\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, DocumentEntities)\n\ntext = \"Tim Cook met with Satya Nadella at Microsoft headquarters in Redmond.\"\nprompt = f\"Extract entities from: {text}\"\n\nresult = generator(prompt)\nfor entity in result.entities:\n    print(f\"{entity.name} ({entity.type})\")\n```\n\n### Pattern 5: Code Generation\n\n```python\nclass PythonFunction(BaseModel):\n    function_name: str\n    parameters: list[str]\n    docstring: str\n    body: str\n\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\ngenerator = outlines.generate.json(model, PythonFunction)\n\nprompt = \"Generate a Python function to calculate factorial\"\nfunc = generator(prompt)\n\nprint(f\"def {func.function_name}({', '.join(func.parameters)}):\")\nprint(f'    \"\"\"{func.docstring}\"\"\"')\nprint(f\"    {func.body}\")\n```\n\n### Pattern 6: Batch Processing\n\n```python\ndef batch_extract(texts: list[str], schema: type[BaseModel]):\n    \"\"\"Extract structured data from multiple texts.\"\"\"\n    model = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n    generator = outlines.generate.json(model, schema)\n\n    results = []\n    for text in texts:\n        result = generator(f\"Extract from: {text}\")\n        results.append(result)\n\n    return results\n\nclass Person(BaseModel):\n    name: str\n    age: int\n\ntexts = [\n    \"John is 30 years old\",\n    \"Alice is 25 years old\",\n    \"Bob is 40 years old\"\n]\n\npeople = batch_extract(texts, Person)\nfor person in people:\n    print(f\"{person.name}: {person.age}\")\n```\n\n## Backend Configuration\n\n### Transformers\n\n```python\nimport outlines\n\n# Basic usage\nmodel = outlines.models.transformers(\"microsoft\u002FPhi-3-mini-4k-instruct\")\n\n# GPU configuration\nmodel = outlines.models.transformers(\n    \"microsoft\u002FPhi-3-mini-4k-instruct\",\n    device=\"cuda\",\n    model_kwargs={\"torch_dtype\": \"float16\"}\n)\n\n# Popular models\nmodel = outlines.models.transformers(\"meta-llama\u002FLlama-3.1-8B-Instruct\")\nmodel = outlines.models.transformers(\"mistralai\u002FMistral-7B-Instruct-v0.3\")\nmodel = outlines.models.transformers(\"Qwen\u002FQwen2.5-7B-Instruct\")\n```\n\n### llama.cpp\n\n```python\n# Load GGUF model\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fllama-3.1-8b.Q4_K_M.gguf\",\n    n_ctx=4096,         # Context window\n    n_gpu_layers=35,    # GPU layers\n    n_threads=8         # CPU threads\n)\n\n# Full GPU offload\nmodel = outlines.models.llamacpp(\n    \".\u002Fmodels\u002Fmodel.gguf\",\n    n_gpu_layers=-1  # All layers on GPU\n)\n```\n\n### vLLM (Production)\n\n```python\n# Single GPU\nmodel = outlines.models.vllm(\"meta-llama\u002FLlama-3.1-8B-Instruct\")\n\n# Multi-GPU\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-70B-Instruct\",\n    tensor_parallel_size=4  # 4 GPUs\n)\n\n# With quantization\nmodel = outlines.models.vllm(\n    \"meta-llama\u002FLlama-3.1-8B-Instruct\",\n    quantization=\"awq\"  # Or \"gptq\"\n)\n```\n\n## Best Practices\n\n### 1. Use Specific Types\n\n```python\n# ✅ Good: Specific types\nclass Product(BaseModel):\n    name: str\n    price: float  # Not str\n    quantity: int  # Not str\n    in_stock: bool  # Not str\n\n# ❌ Bad: Everything as string\nclass Product(BaseModel):\n    name: str\n    price: str  # Should be float\n    quantity: str  # Should be int\n```\n\n### 2. Add Constraints\n\n```python\nfrom pydantic import Field\n\n# ✅ Good: With constraints\nclass User(BaseModel):\n    name: str = Field(min_length=1, max_length=100)\n    age: int = Field(ge=0, le=120)\n    email: str = Field(pattern=r\"^[\\w\\.-]+@[\\w\\.-]+\\.\\w+$\")\n\n# ❌ Bad: No constraints\nclass User(BaseModel):\n    name: str\n    age: int\n    email: str\n```\n\n### 3. Use Enums for Categories\n\n```python\n# ✅ Good: Enum for fixed set\nclass Priority(str, Enum):\n    LOW = \"low\"\n    MEDIUM = \"medium\"\n    HIGH = \"high\"\n\nclass Task(BaseModel):\n    title: str\n    priority: Priority\n\n# ❌ Bad: Free-form string\nclass Task(BaseModel):\n    title: str\n    priority: str  # Can be anything\n```\n\n### 4. Provide Context in Prompts\n\n```python\n# ✅ Good: Clear context\nprompt = \"\"\"\nExtract product information from the following text.\nText: iPhone 15 Pro costs $999 and is currently in stock.\nProduct:\n\"\"\"\n\n# ❌ Bad: Minimal context\nprompt = \"iPhone 15 Pro costs $999 and is currently in stock.\"\n```\n\n### 5. Handle Optional Fields\n\n```python\nfrom typing import Optional\n\n# ✅ Good: Optional fields for incomplete data\nclass Article(BaseModel):\n    title: str  # Required\n    author: Optional[str] = None  # Optional\n    date: Optional[str] = None  # Optional\n    tags: list[str] = []  # Default empty list\n\n# Can succeed even if author\u002Fdate missing\n```\n\n## Comparison to Alternatives\n\n| Feature | Outlines | Instructor | Guidance | LMQL |\n|---------|----------|------------|----------|------|\n| Pydantic Support | ✅ Native | ✅ Native | ❌ No | ❌ No |\n| JSON Schema | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes |\n| Regex Constraints | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |\n| Local Models | ✅ Full | ⚠️ Limited | ✅ Full | ✅ Full |\n| API Models | ⚠️ Limited | ✅ Full | ✅ Full | ✅ Full |\n| Zero Overhead | ✅ Yes | ❌ No | ⚠️ Partial | ✅ Yes |\n| Automatic Retrying | ❌ No | ✅ Yes | ❌ No | ❌ No |\n| Learning Curve | Low | Low | Low | High |\n\n**When to choose Outlines:**\n- Using local models (Transformers, llama.cpp, vLLM)\n- Need maximum inference speed\n- Want Pydantic model support\n- Require zero-overhead structured generation\n- Control token sampling process\n\n**When to choose alternatives:**\n- Instructor: Need API models with automatic retrying\n- Guidance: Need token healing and complex workflows\n- LMQL: Prefer declarative query syntax\n\n## Performance Characteristics\n\n**Speed:**\n- **Zero overhead**: Structured generation as fast as unconstrained\n- **Fast-forward optimization**: Skips deterministic tokens\n- **1.2-2x faster** than post-generation validation approaches\n\n**Memory:**\n- FSM compiled once per schema (cached)\n- Minimal runtime overhead\n- Efficient with vLLM for high throughput\n\n**Accuracy:**\n- **100% valid outputs** (guaranteed by FSM)\n- No retry loops needed\n- Deterministic token filtering\n\n## Resources\n\n- **Documentation**: https:\u002F\u002Foutlines-dev.github.io\u002Foutlines\n- **GitHub**: https:\u002F\u002Fgithub.com\u002Foutlines-dev\u002Foutlines (8k+ stars)\n- **Discord**: https:\u002F\u002Fdiscord.gg\u002FR9DSu34mGd\n- **Blog**: https:\u002F\u002Fblog.dottxt.co\n\n## See Also\n\n- `references\u002Fjson_generation.md` - Comprehensive JSON and Pydantic patterns\n- `references\u002Fbackends.md` - Backend-specific configuration\n- `references\u002Fexamples.md` - Production-ready examples\n\n\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"description":7,"dependencies":39},"Orchestra Research","1.0.0",{"hermes":27},{"tags":28},[29,30,31,32,33,34,35,36,37,38],"Prompt Engineering","Outlines","Structured Generation","JSON Schema","Pydantic","Local Models","Grammar-Based Generation","vLLM","Transformers","Type Safety",[5,40,41,42],"transformers","vllm","pydantic","main","a0559bb2eb5ae47d603efe32afe4589f77bf4ded","src\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus","https:\u002F\u002Fgithub.com\u002Fpvbang","pvbang.github.io\u002Fcv","\u003C\u002F> It's a pleasure to meet you","2026-11-13 16:52:49",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add pvbang\u002Fnexus --skill outlines",{"tool":57,"command":58},"bunx","bunx skills add pvbang\u002Fnexus --skill outlines",{"tool":60,"command":61},"pnpm","pnpm dlx skills add pvbang\u002Fnexus --skill outlines","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines\u002FSKILL.md",true,[65,71,75],{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Fbackends.md","REFERENCE","参考文档",14407,"https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines\u002Freferences\u002Fbackends.md",{"path":72,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Fexamples.md",21231,"https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines\u002Freferences\u002Fexamples.md",{"path":76,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fjson_generation.md",14932,"https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fmlops\u002Finference\u002Foutlines\u002Freferences\u002Fjson_generation.md",[80,89,97,104,111,118],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":84,"licenseFileUrl":85,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M78EFV6FYHV11YKAKYXPND85","skill-creator","Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory (moving files to references\u002F or scripts\u002F, removing stale content, validating against the AgentSkills spec). Triggers on phrases like \"create a skill\", \"author a skill\", \"tidy up a skill\", \"improve this skill\", \"review the skill\", \"clean up the skill\", \"audit the skill\".","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fopenclaw\u002Fskills\u002Fskill-creator\u002Flicense.txt","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fopenclaw\u002Fskills\u002Fskill-creator\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":93,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M78EC37DFKY5X6RFQ6XPE9EY","prose","OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fopenclaw\u002Fextensions\u002Fopen-prose\u002Fskills\u002Fprose\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fopenclaw\u002Fextensions\u002Fopen-prose\u002Fskills\u002Fprose\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M78E9C2RKT5BJ8ZR9KZTNS2A","writing-plans","Write implementation plans: bite-sized tasks, paths, code.","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":19},"01M78E98QY8PH80R7QN1P8NMTH","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":19},"01M78E93DGFNKP1WZ9WJ9S9N7H","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":19},"01M78E8ZM4CER22PJT0WJ1RWMJ","subagent-driven-development","Execute plans via delegate_task subagents (2-stage review).","https:\u002F\u002Fgithub.com\u002Fpvbang\u002Fnexus\u002Fblob\u002Fmain\u002Fsrc\u002Fopen-source\u002Fhermes-agent\u002Fskills\u002Fsoftware-development\u002Fsubagent-driven-development\u002FSKILL.md",[],[]]