{
"canonical_name": "dottxt-ai/outlines",
"compilation_id": "pack_e765ca5231e647f7ac271b7ca6840055",
"created_at": "2026-05-21T23:42:02.179843+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=prompt, recipe, host_instruction, eval, preflight",
"recommended_asset_types=prompt, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install outlines` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install outlines",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_6742779e1ab54c1781368925f35d8fa4"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_373c825fe18929b16c013d606104bf55",
"canonical_name": "dottxt-ai/outlines",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/dottxt-ai/outlines",
"slug": "outlines",
"source_packet_id": "phit_7cb79d12619d40d2b92d1beb3eb45251",
"source_validation_id": "dval_12464c5413314f709980a9b98f4740c4"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 698,
"github_stars": 13848,
"one_liner_en": "Structured Outputs",
"one_liner_zh": "Structured Outputs",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "outlines",
"title_zh": "outlines 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_7cb79d12619d40d2b92d1beb3eb45251",
"page_model": {
"artifacts": {
"artifact_slug": "outlines",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install outlines",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/dottxt-ai/outlines#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Structured Outputs"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "prompt, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature] Streaming structured generation with partial validation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add more custom types",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add function calling and MCP support",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature Request] Add streaming support for structured generation",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "Developers should check this installation risk before relying on the project: Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_aafbb33fe2e219639553f4d4275e0223 | https://github.com/dottxt-ai/outlines/issues/1864 | Feature request: OWASP ASI06 memory poisoning defense for structured generation"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Feature request: OWASP ASI06 memory poisoning defense for structured generation. Context: Observed when using python",
"title": "失败模式：installation: Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"user_impact": "Developers may fail before the first successful local run: Feature request: OWASP ASI06 memory poisoning defense for structured generation"
},
{
"body": "Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda",
"title": "失败模式：installation: Incompatibility with vllm==0.19 because of some api changes",
"user_impact": "Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes"
},
{
"body": "Developers should check this installation risk before relying on the project: Outlines v1.2.6",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.",
"title": "失败模式：installation: Outlines v1.2.6",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.6"
},
{
"body": "Developers should check this installation risk before relying on the project: Outlines v1.2.8",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python",
"title": "失败模式：installation: Outlines v1.2.8",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.8"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "Developers should check this migration risk before relying on the project: Outlines v1.2.10",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python",
"title": "失败模式：migration: Outlines v1.2.10",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.2.10"
},
{
"body": "Developers should check this migration risk before relying on the project: Outlines v1.3.0",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.",
"title": "失败模式：migration: Outlines v1.3.0",
"user_impact": "Upgrade or migration may change expected behavior: Outlines v1.3.0"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Complex structure makes output empty",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 30 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Streaming structured generation with partial validation。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 156,
"forks": 698,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 13848
},
"source_url": "https://github.com/dottxt-ai/outlines",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Structured Outputs",
"title": "outlines 能力包",
"trial_prompt": "# outlines - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for dottxt-ai/outlines.\n\nProject:\n- Name: outlines\n- Repository: https://github.com/dottxt-ai/outlines\n- Summary: Structured Outputs\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Structured Outputs\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Structured Outputs\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Outlines. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quickstart Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-installation: Installation. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-core-concepts: Core Concepts. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/dottxt-ai/outlines\n- https://github.com/dottxt-ai/outlines#readme\n- README.md\n- outlines/__init__.py\n- outlines/release_note.md\n- docs/guide/getting_started.md\n- docs/guide/installation.md\n- pyproject.toml\n- environment.yml\n- docs/guide/architecture.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Feature request: OWASP ASI06 memory poisoning defense for structured gen（https://github.com/dottxt-ai/outlines/issues/1864）；github/github_issue: [Feature Request] Add streaming support for structured generation（https://github.com/dottxt-ai/outlines/issues/1842）；github/github_issue: Add more custom types（https://github.com/dottxt-ai/outlines/issues/1303）；github/github_issue: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation（https://github.com/dottxt-ai/outlines/issues/1859）；github/github_issue: [Feature] Streaming structured generation with partial validation（https://github.com/dottxt-ai/outlines/issues/1856）；github/github_issue: Complex structure makes output empty（https://github.com/dottxt-ai/outlines/issues/1861）；github/github_issue: TransformerTokenizer reads attributes from raw backend that modern trans（https://github.com/dottxt-ai/outlines/issues/1847）；github/github_issue: Incompatibility with vllm==0.19 because of some api changes（https://github.com/dottxt-ai/outlines/issues/1854）；github/github_issue: Add function calling and MCP support（https://github.com/dottxt-ai/outlines/issues/1626）；github/github_release: Outlines v1.3.0（https://github.com/dottxt-ai/outlines/releases/tag/1.3.0）；github/github_release: Outlines v1.2.12（https://github.com/dottxt-ai/outlines/releases/tag/1.2.13）；github/github_release: Outlines v1.2.10（https://github.com/dottxt-ai/outlines/releases/tag/1.2.10）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature request: OWASP ASI06 memory poisoning defense for structured gen",
"url": "https://github.com/dottxt-ai/outlines/issues/1864"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request] Add streaming support for structured generation",
"url": "https://github.com/dottxt-ai/outlines/issues/1842"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add more custom types",
"url": "https://github.com/dottxt-ai/outlines/issues/1303"
},
{
"kind": "github_issue",
"source": "github",
"title": "📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation",
"url": "https://github.com/dottxt-ai/outlines/issues/1859"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature] Streaming structured generation with partial validation",
"url": "https://github.com/dottxt-ai/outlines/issues/1856"
},
{
"kind": "github_issue",
"source": "github",
"title": "Complex structure makes output empty",
"url": "https://github.com/dottxt-ai/outlines/issues/1861"
},
{
"kind": "github_issue",
"source": "github",
"title": "TransformerTokenizer reads attributes from raw backend that modern trans",
"url": "https://github.com/dottxt-ai/outlines/issues/1847"
},
{
"kind": "github_issue",
"source": "github",
"title": "Incompatibility with vllm==0.19 because of some api changes",
"url": "https://github.com/dottxt-ai/outlines/issues/1854"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add function calling and MCP support",
"url": "https://github.com/dottxt-ai/outlines/issues/1626"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.3.0",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.3.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.2.12",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.2.13"
},
{
"kind": "github_release",
"source": "github",
"title": "Outlines v1.2.10",
"url": "https://github.com/dottxt-ai/outlines/releases/tag/1.2.10"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Structured Outputs",
"effort": "安装已验证",
"forks": 698,
"icon": "code",
"name": "outlines 能力包",
"risk": "可发布",
"slug": "outlines",
"stars": 13848,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "Prompt Preview"
},
"manual": {
"markdown": "# https://github.com/dottxt-ai/outlines Project Manual\n\nGenerated on: 2026-05-21 17:36:40 UTC\n\n## Table of Contents\n\n- [Introduction to Outlines](#page-introduction)\n- [Quickstart Guide](#page-quickstart)\n- [Installation](#page-installation)\n- [Migration Guide](#page-migration)\n- [System Architecture](#page-architecture)\n- [Core Concepts](#page-core-concepts)\n- [Structured Generation Backends](#page-backends)\n- [Output Types Overview](#page-output-types)\n- [JSON Schema and Pydantic Support](#page-json-schemas)\n- [Regex Patterns](#page-regex-patterns)\n\n\n\n## Introduction to Outlines\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture), [Quickstart Guide](#page-quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n \n\n# Introduction to Outlines\n\nOutlines is a Python library that enables **structured text generation** with Large Language Models (LLMs). It guarantees that model outputs conform to a specified structure during generation, eliminating the need for post-processing, regex parsing, or fragile code that breaks easily. Source: [README.md]()\n\n## What Problem Does Outlines Solve?\n\nLLMs are powerful but produce unpredictable outputs. Traditional approaches attempt to fix bad outputs after generation using parsing and regex, which is fragile and breaks easily. Outlines takes a different approach by ensuring structured outputs **during generation** rather than after. Source: [README.md]()\n\nThe core philosophy follows Python's own type system pattern: simply specify the desired output type, and Outlines ensures the generated data matches that structure exactly. Source: [README.md]()\n\n## Core Philosophy\n\nOutlines follows a simple pattern that mirrors Python's own type system:\n\n- For yes/no responses, use `Literal[\"Yes\", \"No\"]`\n- For numerical values, use `int`\n- For complex objects, define a structure with a [Pydantic model](https://docs.pydantic.dev/latest/)\n\nThis type-driven API makes structured generation feel natural to Python developers. Source: [README.md]()\n\n## Key Features\n\n### Universal Model Support\n\nOutlines works with any model provider with minimal code changes:\n\n| Model Type | Description | Documentation |\n|------------|-------------|---------------|\n| **Server Support** | vLLM and Ollama | Server Integrations |\n| **Local Model Support** | transformers and llama.cpp | Model Integrations |\n| **API Support** | OpenAI, Gemini, and Dottxt | API Integrations |\n\nSource: [README.md]()\n\n### Guaranteed Valid Structure\n\nOutlines provides several key guarantees:\n\n- **Works with any model** - Same code runs across OpenAI, Ollama, vLLM, and more\n- **Simple integration** - Just pass your desired output type: `model(prompt, output_type)`\n- **Guaranteed valid structure** - No more parsing headaches or broken JSON\n- **Provider independence** - Switch models without changing code\n\nSource: [README.md]()\n\n## Architecture Overview\n\n### Layer Stack\n\nOutlines follows a multi-layered architecture that transforms Python types into generation constraints:\n\n```\nUser API (outlines.models)\n ↓\nGenerator Classes (SteerableGenerator, BlackBoxGenerator)\n ↓\nType System (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM Compilation (outlines-core: regex → FSM via interegular)\n ↓\nGuide System (processors/guide.py: FSM state management)\n ↓\nLogits Processing (processors/structured.py: token masking)\n ↓\nModel Providers (transformers, OpenAI, etc.)\n```\n\nSource: [llm.txt]()\n\n### Key Design Decisions\n\n1. **FSM-based constraints**: For local models, constraints compile to finite state machines that track valid next tokens\n2. **Provider abstraction**: Same constraint system works across local models (transformers) and APIs (OpenAI)\n3. **Lazy compilation**: FSMs are compiled on first use and cached persistently\n4. **Token-level control**: Constraints apply at the token level, not character level\n5. **Type-driven API**: Python types are the primary interface for specifying constraints\n\nSource: [llm.txt]()\n\n### Model Class Hierarchy\n\nOutlines distinguishes between two types of model implementations:\n\n```mermaid\ngraph TD\n BaseModel[BaseModel]\n SteerableModel[SteerableModel - Controls logits]\n BlackBoxModel[BlackBoxModel - Uses provider's structured output]\n \n BaseModel --> SteerableModel\n BaseModel --> BlackBoxModel\n \n SteerableModel --> Transformers[Transformers]\n SteerableModel --> LlamaCpp[LlamaCpp]\n \n BlackBoxModel --> OpenAI[OpenAI]\n BlackBoxModel --> Gemini[Gemini]\n BlackBoxModel --> Anthropic[Anthropic]\n```\n\nSource: [llm.txt]()\n\n## Getting Started\n\n### Installation\n\nInstall Outlines using pip:\n\n```shell\npip install outlines\n```\n\nSource: [README.md]()\n\n### Basic Usage\n\n#### 1. Connect to a Model\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nSource: [README.md]()\n\n#### 2. Simple Structured Outputs\n\n```python\nfrom typing import Literal\nfrom pydantic import BaseModel\n\n\n# Simple classification\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n\n# Extract specific types\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\nSource: [README.md]()\n\n#### 3. Complex Structures with Pydantic\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\nSource: [README.md]()\n\n### Using Templates\n\nOutlines supports Jinja-based templates for dynamic prompt generation:\n\n```python\nimport outlines\nfrom typing import List, Literal\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/phi-4\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\n\n# Create a reusable template with Jinja syntax\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start>assistant\n\"\"\")\n\n# Generate prompts with different parameters\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# Use with structured generation\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\nSource: [README.md]()\n\n## Generator Pattern\n\nThe `Generator` class provides a reusable way to apply structured generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a generator with a specific output type\ngenerator = Generator(model, MyOutputType)\n\n# Reuse the generator multiple times\nresult1 = generator(\"Prompt 1\")\nresult2 = generator(\"Prompt 2\")\n```\n\nThe Generator class was introduced in v1 to address the need for reusable generation with a fixed output type, where output type compilation happens only once. Source: [outlines/release_note.md]()\n\n## Async Support\n\nOutlines provides comprehensive async support for both generation and streaming:\n\n### Async Model Methods\n\n```python\n# Direct model calling with async\nfrom pydantic import BaseModel\nfrom outlines import from_openai\nfrom openai import AsyncOpenAI\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_openai(AsyncOpenAI(), \"gpt-4o\")\nresult = await model(\"Create a character\", Character)\n```\n\nSource: [outlines/models/base.py]()\n\n### Async Streaming\n\n```python\nasync for chunk in model.stream(\"prompt\", OutputType):\n print(chunk)\n```\n\nSource: [outlines/models/base.py]()\n\n### Batch Processing\n\n```python\n# Batch generation\nresults = await model.batch([\"prompt1\", \"prompt2\"], OutputType)\n```\n\nSource: [outlines/models/base.py]()\n\n## API Model Integration\n\n### OpenAI\n\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import from_openai\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nSource: [outlines/release_note.md]()\n\n### Google Gemini\n\n```python\nfrom outlines import from_gemini\n\nmodel = from_gemini(client, \"gemini-pro\")\n```\n\nSource: [outlines/models/gemini.py]()\n\n## Exception Handling\n\nOutlines provides a comprehensive exception hierarchy for error handling:\n\n```\nOutlinesError\n├── APIError\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ ├── ServerError\n│ ├── APITimeoutError\n│ ├── APIConnectionError\n│ └── ProviderResponseError\n└── GenerationError\n```\n\nSource: [outlines/exceptions.py]()\n\nAll public exceptions inherit from `APIError` → `OutlinesError` → `Exception`. The `normalize_provider_exception` function converts raw provider SDK exceptions into the appropriate Outlines type. Source: [outlines/exceptions.py]()\n\n## Deployment Example\n\nOutlines can be deployed on various platforms. Here's an example using Modal:\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n\n\ndef import_model():\n from transformers import AutoModelForCausalLM, AutoTokenizer\n\n model_id = \"mistralai/Mistral-7B-Instruct-v0.2\"\n _ = AutoTokenizer.from_pretrained(model_id)\n _ = AutoModelForCausalLM.from_pretrained(model_id)\n\n\noutlines_image = outlines_image.run_function(import_model)\n```\n\nSource: [examples/modal_example.py]()\n\n## Migration from v0 to v1\n\nKey changes in the v1 API:\n\n| Feature | v0 | v1 |\n|---------|----|----|\n| Model initialization | `models.openai(\"gpt-4o\")` | `from_openai(OpenAI(), \"gpt-4o\")` |\n| Generation | `generate.json(model, Character)` | `Generator(model, Character)` |\n| Direct calling | N/A | `model(\"prompt\", OutputType)` |\n| Streaming | Separate method | `model.stream(\"prompt\", OutputType)` |\n\nSource: [outlines/release_note.md]()\n\n### Deprecated Features\n\n- `Exllamav2` model has been removed due to interface incompatibility\n- `function` module and `Function` class replaced by `Application`\n- `load_lora` methods on `VLLM` and `LlamaCpp` models deprecated in favor of direct initialization parameters\n- `TransformersVision` replaced by `TransformersMultiModal`\n\nSource: [outlines/release_note.md]()\n\n## See Also\n\n- [Model Integrations](../features/models/) - Detailed documentation for each model provider\n- [Generator](../features/core/generator/) - Generator class documentation\n- [Application](../features/utility/application/) - Application class for templated prompts\n- [Templates](../features/utility/template/) - Jinja-based template system\n\n---\n\n\n\n## Quickstart Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Outlines](#page-introduction), [Installation](#page-installation), [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# Quickstart Guide\n\nThis guide provides a comprehensive introduction to Outlines, a structured text generation library for Large Language Models (LLMs). It covers installation, model setup, basic usage patterns, and common workflows to help you get started with guaranteed structured outputs from any LLM.\n\n## Overview\n\nOutlines ensures structured outputs during generation—directly from any LLM. Unlike post-processing approaches that parse and validate outputs after generation, Outlines enforces structure constraints at generation time. This eliminates parsing headaches, broken JSON, and fragile regex-based solutions.\n\n**Core capabilities:**\n\n- Works with any model (OpenAI, Ollama, vLLM, transformers, and more)\n- Simple integration using Python type annotations\n- Guaranteed valid structure output\n- Provider independence for easy model switching\n\nSource: [README.md:1-10]()\n\n## Installation\n\nInstall Outlines using pip:\n\n```shell\npip install outlines\n```\n\nSource: [README.md:31]()\n\n### Optional Dependencies\n\nDepending on your model provider, you may need additional packages:\n\n| Provider | Required Dependencies |\n|----------|----------------------|\n| transformers | `transformers`, `accelerate` |\n| OpenAI | `openai` |\n| Anthropic | `anthropic` |\n| Gemini | `google-genai` |\n| vLLM | `vllm` |\n| Ollama | `ollama` |\n\n## Connecting to Models\n\nOutlines provides factory functions to create model instances from various providers. The `from_transformers` function initializes a model using Hugging Face transformers.\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nSource: [README.md:37-46]()\n\n### Available Model Integrations\n\nOutlines supports multiple model providers through factory functions:\n\n| Model Type | Factory Function | Description |\n|------------|------------------|-------------|\n| Local (Transformers) | `from_transformers()` | Hugging Face transformers models |\n| OpenAI | `from_openai()` | OpenAI API models |\n| Anthropic | `from_anthropic()` | Anthropic Claude models |\n| Gemini | `from_gemini()` | Google Gemini models |\n| vLLM | `from_vllm()` | vLLM server deployment |\n| Ollama | `from_ollama()` | Ollama local server |\n| llama.cpp | `from_llamacpp()` | llama.cpp based models |\n\nSource: [llm.txt:1-20]()\n\n## Basic Structured Generation\n\n### Simple Classification\n\nUse `Literal` types for classification tasks with predefined categories:\n\n```python\nfrom typing import Literal\n\n# Simple classification\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\nSource: [README.md:55-62]()\n\n### Numerical Values\n\nGenerate structured numerical outputs by passing Python types:\n\n```python\n# Extract numerical values\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\nSource: [README.md:64-68]()\n\n### State Flow for Basic Generation\n\n```mermaid\ngraph TD\n A[User Prompt + Type] --> B[Outlines Model Call]\n B --> C{Output Type}\n C -->|Literal| D[Enum FSM Compilation]\n C -->|int/float| E[Number FSM Compilation]\n C -->|Pydantic| F[JSON Schema FSM Compilation]\n D --> G[Token Masking]\n E --> G\n F --> G\n G --> H[Constrained Generation]\n H --> I[Valid Structured Output]\n```\n\n## Complex Structures with Pydantic\n\nFor complex objects, define a structure using Pydantic models:\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\n# Generate structured review\nreview = model(\n \"Review a smartphone with great camera but poor battery life\",\n ProductReview\n)\n```\n\nSource: [README.md:70-88]()\n\n### Enum Types\n\nEnums constrain outputs to specific string values:\n\n```python\nfrom enum import Enum\n\nclass EventType(str, Enum):\n conference = \"conference\"\n webinar = \"webinar\"\n workshop = \"workshop\"\n meetup = \"meetup\"\n other = \"other\"\n\nclass EventInfo(BaseModel):\n name: str\n event_type: EventType\n topics: list[str]\n```\n\nSource: [README.md:1-50]()\n\n## Prompt Templates\n\nOutlines supports Jinja-based templates for dynamic prompt generation:\n\n```python\n# Create a reusable template with Jinja syntax\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start|>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start>assistant\n\"\"\")\n\n# Generate prompts with different parameters\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# Use with structured generation\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\nSource: [README.md:1-50]()\n\n### Loading Templates from Files\n\nTemplates can be loaded from external files for better organization:\n\n```python\n# Load template from file\nexample_template = outlines.Template.from_file(\"templates/few_shot.txt\")\n\n# Use with examples for few-shot learning\nexamples = [\n (\"The food was cold\", \"Negative\"),\n (\"The staff was friendly\", \"Positive\")\n]\nfew_shot_prompt = example_template(examples=examples, query=\"Service was slow\")\n```\n\nSource: [README.md:1-50]()\n\n## Handling Incomplete Data with Union Types\n\nUse Union types to handle cases where data might be incomplete:\n\n```python\nfrom typing import Union\n\n# Create a union type that can either be a structured response or fallback\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\n# Parse event details - returns EventInfo or \"I don't know\"\nresult = model(\n \"Join us for DevCon 2024 in San Francisco on March 15th\",\n EventResponse\n)\n```\n\nSource: [README.md:1-50]()\n\n## Using the Generator Class\n\nThe `Generator` class encapsulates a model with a specific output type, allowing reusable structured generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom typing import Literal\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a reusable generator\nchoice_generator = Generator(model, Literal[\"pizza\", \"burger\", \"tacos\"])\n\n# Use the generator multiple times\nresult1 = choice_generator(\"What should I eat for lunch?\")\nresult2 = choice_generator(\"Dinner options?\")\n```\n\nSource: [outlines/release_note.md:1-50]()\n\n### Generator vs Direct Model Calling\n\n| Aspect | Direct Model Call | Generator |\n|--------|-------------------|-----------|\n| Output type | Specified per call | Fixed at initialization |\n| Compilation | Occurs each call | Occurs once |\n| Reusability | Single use | Multiple uses |\n| Best for | Varying output types | Consistent output types |\n\nSource: [outlines/release_note.md:1-50]()\n\n## Function Calling with Applications\n\nThe `Application` class provides a way to define functions with typed parameters that LLMs can call:\n\n```python\nfrom outlines import Application, Template, from_transformers\nfrom pydantic import BaseModel\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom typing import List, Optional\nfrom datetime import date\n\n# Define a function with typed parameters\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None,\n agenda_items: Optional[List[str]] = None\n):\n \"\"\"Schedule a meeting with the specified details\"\"\"\n meeting = {\n \"title\": title,\n \"date\": date,\n \"duration_minutes\": duration_minutes,\n \"attendees\": attendees,\n \"location\": location,\n \"agenda_items\": agenda_items\n }\n return f\"Meeting '{title}' scheduled for {date}\"\n\n# Create model and template\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/phi-4\"),\n AutoTokenizer.from_pretrained(\"microsoft/phi-4\")\n)\n\ntemplate = Template.from_string(\"\"\"\nExtract meeting details from: {{ request }}\n\"\"\")\n\n# Create application\napp = Application(template, schedule_meeting)\n\n# Natural language request\nuser_request = \"\"\"\nI need to set up a team sync next Monday at 2pm for 30 minutes.\nInclude John and Sarah. We'll discuss the Q1 roadmap.\n\"\"\"\n\n# Execute\nresult = app(model, {\"request\": user_request})\n```\n\nSource: [README.md:1-50]()\n\n### Application Pattern Workflow\n\n```mermaid\ngraph TD\n A[Natural Language Request] --> B[Application]\n B --> C[Template Variables]\n C --> D[Structured Prompt]\n D --> E[LLM Generation]\n E --> F[Function Schema]\n F --> G[Parameter Extraction]\n G --> H[Typed Function Call]\n H --> I[Structured Result]\n```\n\n## Generation Parameters\n\nPass additional inference arguments to model calls:\n\n```python\n# Beam search for better quality\nresult = model(\n \"Write a short story about a cat\",\n str,\n num_beams=2\n)\n\n# Streaming responses\nfor chunk in model.stream(\"Tell me a joke\", str):\n print(chunk, end=\"\", flush=True)\n```\n\nSource: [outlines/release_note.md:1-50]()\n\n## Deployment Examples\n\n### Modal Deployment\n\nOutlines can be deployed on Modal for serverless inference:\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n\ndef import_model():\n from transformers import AutoModelForCausalLM, AutoTokenizer\n model_id = \"mistralai/Mistral-7B-Instruct-v0.2\"\n _ = AutoTokenizer.from_pretrained(model_id)\n _ = AutoModelForCausalLM.from_pretrained(model_id)\n\noutlines_image = outlines_image.run_function(import_model)\n```\n\nSource: [examples/modal_example.py:1-30]()\n\n## Next Steps\n\n| Topic | Description |\n|-------|-------------|\n| [Installation Guide](guide/installation.md) | Detailed installation instructions for all providers |\n| [Model Integrations](features/models/index.md) | Complete reference for all supported models |\n| [Output Types](features/core/output_types.md) | Deep dive into type system and constraints |\n| [Templates](features/utility/template.md) | Advanced template usage and patterns |\n| [Applications](features/utility/application.md) | Building reusable structured applications |\n| [Architecture](guide/architecture.md) | Understanding the internal design |\n\n## Quick Reference\n\n```python\n# Complete minimal example\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom pydantic import BaseModel\n\n# 1. Load model\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 2. Define output structure\nclass Answer(BaseModel):\n response: str\n confidence: float\n\n# 3. Generate with structure guarantee\nresult = model(\"What is the capital of France?\", Answer)\n```\n\nThis quickstart covers the essential patterns for using Outlines. The library's type-driven approach ensures that outputs always match your specified structure, eliminating the need for fragile post-processing.\n\n---\n\n\n\n## Installation\n\n### Related Pages\n\nRelated topics: [Quickstart Guide](#page-quickstart), [Structured Generation Backends](#page-backends)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottext-ai/outlines/blob/main/README.md)\n- [release_note.md](https://github.com/dottxt-ai/outlines/blob/main/release_note.md)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n \n\n# Installation\n\nThis guide covers all methods for installing Outlines, a structured text generation library for Large Language Models.\n\n## Overview\n\nOutlines provides structured output generation for LLMs by ensuring outputs match specified types during generation. The installation process is straightforward via pip, with optional dependencies for specific model backends. Source: [README.md:1-10]()\n\n## Prerequisites\n\n### Python Version\n\nOutlines requires Python 3.10 or later. Ensure your environment has an appropriate Python installation before proceeding.\n\n### Core Dependencies\n\nThe following table lists the core dependencies required by Outlines:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `interegular` | Latest | FSM compilation for regex-based constraints |\n| `jinja2` | Latest | Template processing |\n| `pydantic` | 2.x | Data validation and structure definitions |\n\n## Installation Methods\n\n### Standard Installation (pip)\n\nThe simplest way to install Outlines is via pip:\n\n```bash\npip install outlines\n```\n\nSource: [README.md:15-18]()\n\n### Development Installation\n\nFor contributors or those wanting the latest unreleased features, install from source:\n\n```bash\ngit clone https://github.com/dottxt-ai/outlines.git\ncd outlines\npip install -e \".[dev]\"\n```\n\n## Optional Dependencies by Model Backend\n\nOutlines supports multiple model providers. Install backend-specific dependencies based on your use case.\n\n### Hugging Face Transformers\n\nFor local model inference using Hugging Face Transformers:\n\n```bash\npip install outlines[transformers]\n```\n\nRequired packages:\n\n| Package | Purpose |\n|---------|---------|\n| `transformers` | Model loading and inference |\n| `accelerate` | GPU acceleration support |\n| `datasets` | Dataset utilities |\n| `torch` | Deep learning framework |\n\nSource: [examples/modal_example.py:5-9]()\n\n```python\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n### OpenAI Models\n\nFor OpenAI API integration:\n\n```bash\npip install outlines[openai]\n```\n\nRequired packages:\n\n| Package | Purpose |\n|---------|---------|\n| `openai` | Official OpenAI Python client |\n\nSource: [README.md:20-35]()\n\n```python\nfrom openai import OpenAI\nfrom outlines import from_openai\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\n### Anthropic Models\n\nFor Anthropic Claude integration:\n\n```bash\npip install outlines[anthropic]\n```\n\n### Google Gemini Models\n\n```bash\npip install outlines[gemini]\n```\n\nSource: [outlines/models/gemini.py:80-95]()\n\n### Local Model Backends\n\nFor running models locally via vLLM, llama.cpp, or SGLang:\n\n```bash\npip install outlines[vllm] # For vLLM backend\npip install outlines[sglang] # For SGLang backend\n```\n\nSource: [llm.txt:30-50]()\n\n### Async Support\n\nFor asynchronous inference with async model backends:\n\n```bash\npip install outlines[async]\n```\n\nThe async backends available are:\n\n| Backend | Class | Purpose |\n|---------|-------|---------|\n| AsyncSGLang | `AsyncSGLang` | Async SGLang inference |\n| AsyncTGI | `AsyncTGI` | Async Text Generation Inference |\n| AsyncVLLM | `AsyncVLLM` | Async vLLM inference |\n\nSource: [release_note.md:45-60]()\n\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n## Quick Start After Installation\n\nOnce installed, you can begin using Outlines immediately:\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n# Load a model\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\n# Generate structured output\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\n```\n\nSource: [README.md:40-60]()\n\n## GPU Setup\n\nFor optimal performance with local models, configure GPU acceleration:\n\n```python\n# Device mapping for multi-GPU setups\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\n MODEL_NAME, \n device_map=\"auto\"\n ),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nThe `device_map=\"auto\"` parameter enables automatic GPU allocation across available devices.\n\n## Verifying Installation\n\nVerify your installation by running:\n\n```python\nimport outlines\nprint(outlines.__version__) # Check installed version\n```\n\n## Common Installation Issues\n\n### Missing Dependencies\n\nIf you encounter import errors, ensure all required dependencies are installed for your specific use case. Reinstall with the appropriate extras:\n\n```bash\npip install --upgrade outlines[]\n```\n\n### CUDA/GPU Compatibility\n\nFor CUDA support with transformers, ensure `accelerate` is installed:\n\n```bash\npip install accelerate\n```\n\n### Version Conflicts\n\nIf upgrading from v0.x to v1.x, note the following breaking changes:\n\n| v0.x | v1.x |\n|------|------|\n| `models.openai(\"gpt-4o\")` | `from_openai(OpenAI(), \"gpt-4o\")` |\n| `generate.json(model, schema)` | `model(prompt, schema)` |\n| `Function` class | `Application` class |\n\nSource: [release_note.md:100-130]()\n\n## Next Steps\n\nAfter installation, explore these topics:\n\n- [Quick Start Guide](getting-started.md) - Generate your first structured output\n- [Model Integrations](../features/models.md) - Configure different model backends\n- [Structured Generation](../features/structured-outputs.md) - Learn about type-constrained generation\n\n---\n\n\n\n## Migration Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Outlines](#page-introduction), [Quickstart Guide](#page-quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [docs/guide/migration.md](https://github.com/dottxt-ai/outlines/blob/main/docs/guide/migration.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n \n\n# Migration Guide\n\nThis guide provides comprehensive documentation for migrating from Outlines v0 to v1. The v1 release introduces significant API changes that improve consistency, usability, and maintainability while preserving the core functionality of structured text generation with LLMs.\n\n## Overview\n\nOutlines v1 represents a major evolution of the library's architecture, focusing on:\n\n- **Unified Model Interface**: All model providers now share a consistent calling pattern\n- **Simplified Output Type Handling**: The `Generator` class replaces multiple specialized generate functions\n- **Type-driven API**: Python types remain the primary interface for specifying constraints\n- **Enhanced Streaming**: All models now support streaming as a first-class feature\n\nSource: [outlines/release_note.md:1-50]()\n\n## High-Level Architecture Changes\n\nThe following diagram illustrates the architectural changes between v0 and v1:\n\n```mermaid\ngraph TD\n subgraph v0_Architecture\n A0[User Code] --> B0[models]\n B0 --> C0[generate.json/choice/...]\n C0 --> D0[Generator with fixed output type]\n end\n \n subgraph v1_Architecture\n A1[User Code] --> B1[from_transformers/from_openai/...]\n B1 --> C1[Model Instance]\n A1 --> D1[Generator Model, OutputType]\n D1 --> E1[Reusable Generator]\n end\n \n style v0_Architecture fill:#ffcccc\n style v1_Architecture fill:#ccffcc\n```\n\n## Migration by Component\n\n### Model Initialization\n\n#### Transformers Models\n\n| Aspect | v0 | v1 |\n|--------|-----|-----|\n| Entry point | `models.transformers()` | `outlines.from_transformers()` |\n| Model loading | Inline with Outlines initialization | Separately via HuggingFace |\n| Tokenizer | Passed to Outlines | Explicitly loaded and passed |\n| Configuration | Scattered across `model_kwargs` | Standard HuggingFace initialization |\n\n**v0 (Deprecated):**\n```python\nfrom outlines import models\nfrom transformers import BertForSequenceClassification, BertTokenizer\n\nmodel = models.transformers(\n model_name=\"prajjwal1/bert-tiny\",\n model_class=BertForSequenceClassification,\n tokenizer_class=BertTokenizer,\n model_kwargs={\"use_cache\": False},\n tokenizer_kwargs={\"model_max_length\": 512},\n)\n```\n\n**v1 (Current):**\n```python\nimport outlines\nfrom transformers import BertForSequenceClassification, BertTokenizer\n\nhf_model = BertForSequenceClassification.from_pretrained(\n \"prajjwal1/bert-tiny\", \n use_cache=False\n)\nhf_tokenizer = BertTokenizer.from_pretrained(\n \"prajjwal1/bert-tiny\", \n model_max_length=512\n)\nmodel = outlines.from_transformers(hf_model, hf_tokenizer)\n```\n\nSource: [outlines/release_note.md:45-60]()\n\n#### OpenAI Models\n\n| Aspect | v0 | v1 |\n|--------|-----|-----|\n| Init signature | `OpenAI(client, OpenAIConfig())` | `OpenAI(client, model_name)` |\n| Inference args | In `OpenAIConfig` | In model call |\n| Recommendation | Direct initialization | Use `from_openai()` |\n\n**v0 (Deprecated):**\n```python\nfrom outlines import models\n\nmodel = models.openai(\"gpt-4o\", config)\nresult = generator(\"Create a character\")\n```\n\n**v1 (Current):**\n```python\nfrom openai import OpenAI\nfrom outlines import from_openai\n\nclient = OpenAI()\nmodel = from_openai(client, \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nSource: [outlines/release_note.md:65-80]()\n\n### Generation API Changes\n\n#### Generator Class Introduction\n\nThe `Generator` class provides a reusable interface where the output type is compiled only once:\n\n```mermaid\nclassDiagram\n class Generator {\n +model: Model\n +output_type: OutputType\n +__init__(model, output_type)\n +__call__(prompt, **kwargs) Any\n +stream(prompt, **kwargs) Iterator\n }\n \n class Model {\n <>\n +__call__(prompt, output_type, **kwargs) Any\n +stream(prompt, output_type, **kwargs) Iterator\n }\n \n class OutputType {\n <>\n }\n \n Generator --> Model : uses\n Generator --> OutputType : compiles\n```\n\n**Usage Pattern:**\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a reusable generator\ngenerator = Generator(model, Character)\n\n# Use multiple times without recompiling the output type\nresult1 = generator(\"Create a hero character\")\nresult2 = generator(\"Create a villain character\")\n```\n\nSource: [outlines/release_note.md:25-45]()\n\n#### Direct Model Calling\n\nAll models can now be called directly with a prompt and output type:\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Direct calling with output type\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n\n# Streaming support\nfor chunk in model.stream(\"Tell me a story\", str):\n print(chunk, end=\"\", flush=True)\n```\n\nSource: [outlines/release_note.md:18-25]()\n\n### Function to Application Migration\n\nThe `Function` class has been deprecated in favor of the `Application` class:\n\n| Aspect | v0 (`Function`) | v1 (`Application`) |\n|--------|-----------------|-------------------|\n| Model binding | At initialization | At call time |\n| Template variables | As `**kwargs` | As dictionary |\n| Reusability | Single model/output type | Multiple models supported |\n\n**v0 (Deprecated):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n```\n\n**v1 (Current):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import Application, Template, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\nSource: [outlines/release_note.md:80-95]()\n\n### Generate Module Deprecation\n\nThe `generate` module and its specialized functions have been consolidated:\n\n| v0 Function | v1 Equivalent |\n|-------------|---------------|\n| `generate.json()` | `Generator(model, PydanticModel)` |\n| `generate.choice()` | `Generator(model, Literal[\"A\", \"B\"])` |\n| `generate.regex()` | `Generator(model, str) with FSM constraint` |\n\n**v0 (Deprecated):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import generate, models\n\nclass Character(BaseModel):\n name: str\n\nmodel = models.openai(\"gpt-4o\")\ngenerator = generate.json(model, Character)\nresult = generator(\"Create a character\")\n```\n\n**v1 (Current):**\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_openai\n\nclass Character(BaseModel):\n name: str\n\nclient = OpenAI()\nmodel = from_openai(client, \"gpt-4o\")\ngenerator = Generator(model, Character)\nresult = generator(\"Create a character\")\n```\n\nSource: [outlines/release_note.md:95-110]()\n\n## Async Model Support\n\nv1 introduces new async model providers for asynchronous inference:\n\n| Model | Factory Function | Description |\n|-------|-----------------|-------------|\n| `AsyncSGLang` | `from_sglang()` | SGLang async backend |\n| `AsyncTGI` | `from_tgi()` | Text Generation Inference |\n| `AsyncVLLM` | `from_vllm()` | vLLM async backend |\n\n**Usage:**\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\nSource: [outlines/release_note.md:10-18]()\n\n## Deprecated Features\n\n### Exllamav2 Model\n\nThe `Exllamav2` model has been deprecated without replacement:\n\n- **Reason**: Interface incompatibility with Outlines' constraint system\n- **Impact**: Required cumbersome runtime patching\n- **Action**: Migrate to supported local inference backends (transformers, llama.cpp, vLLM)\n\n## Quick Reference\n\n### Import Changes\n\n| Old Import | New Import |\n|------------|------------|\n| `from outlines import models` | `from outlines import from_transformers, from_openai, ...` |\n| `from outlines import generate` | `from outlines import Generator` |\n| `from outlines import Function` | `from outlines import Application` |\n\n### Common Migration Patterns\n\n```python\n# JSON output - v0 to v1\n# v0: generate.json(model, MySchema)\n# v1: Generator(model, MySchema)\n\n# Choice selection - v0 to v1\n# v0: generate.choice(model, [\"option1\", \"option2\"])\n# v1: model(prompt, Literal[\"option1\", \"option2\"])\n\n# Streaming - v0 to v1\n# v0: generator = generate.json(model, Schema); result = generator.stream(prompt)\n# v1: for chunk in model.stream(prompt, Schema): process(chunk)\n```\n\n## Documentation References\n\nFor additional information, consult the following resources:\n\n- [Models Overview](https://dottxt-ai.github.io/outlines/latest/features/models)\n- [Generator Guide](https://dottxt-ai.github.io/outlines/latest/features/core/generator)\n- [Application Guide](https://dottxt-ai.github.io/outlines/latest/features/utility/application)\n- [Python Types Guide](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/#basic-python-types)\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Structured Generation Backends](#page-backends), [Core Concepts](#page-core-concepts)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [llm.txt](https://github.com/dottext-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [docs/guide/architecture.md](https://github.com/dottxt-ai/outlines/blob/main/docs/guide/architecture.md)\n \n\n# System Architecture\n\n## Overview\n\nOutlines is a structured text generation library for Large Language Models (LLMs). Its core architectural purpose is to guarantee that LLM outputs conform to developer-specified schemas and constraints during generation, rather than attempting to parse and fix invalid outputs after generation.\n\nThe architecture achieves this through a multi-layered system that compiles output type specifications into finite state machines (FSMs), which are then used to constrain token selection at the logits processing level. This approach provides provider independence, allowing the same constraint system to work across both local models (where logits can be directly controlled) and API-based models (where structured output APIs are leveraged when available).\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Layer Stack Architecture\n\nOutlines follows a strict layered architecture where each layer has a specific responsibility and communicates with adjacent layers through well-defined interfaces.\n\n```mermaid\ngraph TD\n A[\"User API
(outlines.models)\"] --> B[\"Generator Classes
(SteerableGenerator, BlackBoxGenerator)\"]\n B --> C[\"Type System
(types/dsl.py)\"]\n C --> D[\"FSM Compilation
(outlines-core: regex → FSM)\"]\n D --> E[\"Guide System
(processors/guide.py)\"]\n E --> F[\"Logits Processing
(processors/structured.py)\"]\n F --> G[\"Model Providers
(transformers, OpenAI, etc.)\"]\n \n style A fill:#e1f5ff\n style G fill:#fff3e1\n style C fill:#e8f5e9\n style D fill:#f3e5f5\n```\n\n### Layer Descriptions\n\n| Layer | File Location | Purpose |\n|-------|---------------|---------|\n| User API | `outlines/models/` | Entry point for model initialization and generation calls |\n| Generator Classes | `outlines/generator.py` | Manages reusable generation with cached FSM compilation |\n| Type System | `outlines/types/dsl.py` | Converts Python types and Pydantic models to JSON Schema and Regex |\n| FSM Compilation | `outlines-core` | Transforms regex patterns into finite state machines via interegular |\n| Guide System | `processors/guide.py` | Manages FSM state transitions during token generation |\n| Logits Processing | `processors/structured.py` | Masks invalid tokens by modifying logits before sampling |\n| Model Providers | `outlines/models/*.py` | Provider-specific adapters for different LLM backends |\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Core Components\n\n### Model Classes\n\nThe model layer defines two fundamental abstract base classes that reflect the fundamental difference in how Outlines interacts with different types of LLM backends.\n\n#### SteerableModel\n\n`SteerableModel` is the base class for models where Outlines has direct control over the sampling process. This includes:\n\n- Local models via the `Transformers` backend\n- llama.cpp-based models via the `Llamacpp` backend\n- MLX-accelerated models via the `MlxLm` backend\n\nFor steerable models, Outlines can apply logits processors that mask invalid tokens based on the compiled FSM, ensuring constraint satisfaction at generation time.\n\nSource: [outlines/models/base.py:1-50](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n#### BlackBoxModel\n\n`BlackBoxModel` is the base class for API-based models where the model provider controls the generation process. This includes:\n\n- OpenAI models\n- Anthropic models\n- Google Gemini models\n- Ollama (when used as an API)\n\nFor black box models, Outlines leverages provider-specific structured output APIs when available, or falls back to prompting strategies. The constraint system cannot directly mask tokens, so the approach adapts based on provider capabilities.\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Generator System\n\nThe `Generator` class provides a reusable abstraction for generation that encapsulates both the model and output type specification.\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(...)\ngenerator = Generator(model, Character)\n\n# FSM compilation happens once\nresult = generator(\"Create a character\")\n```\n\nKey benefits of the Generator abstraction:\n\n1. **Lazy Compilation**: FSMs are compiled on first use and cached persistently\n2. **Reusability**: The same generator can be called multiple times without re-specifying the output type\n3. **Separation of Concerns**: Model configuration and output type specification are decoupled\n\nSource: [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n### Async Model Support\n\nAll model classes inherit from `AsyncModelMixin`, providing consistent async interfaces across all providers:\n\n```python\nasync def __call__(self, model_input, output_type=None, backend=None, **inference_kwargs)\nasync def batch(self, model_inputs, output_type=None, backend=None, **inference_kwargs)\nasync def stream(self, model_input, output_type=None, backend=None, **inference_kwargs)\n```\n\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Provider Abstraction\n\nThe architecture uses a factory pattern with provider-specific adapter classes that handle input and output format conversion.\n\n```mermaid\ngraph LR\n A[User Code] --> B[\"from_transformers() / from_openai() / etc.\"]\n B --> C[\"Model Instance
(Transformers / OpenAI / etc.)\"]\n C --> D[\"Provider Adapter\"]\n D --> E[\"Generation Method\"]\n \n style B fill:#e8f5e9\n```\n\n### Supported Providers\n\n| Provider | Factory Function | Model Class | Control Type |\n|----------|-----------------|-------------|--------------|\n| Hugging Face Transformers | `from_transformers()` | `Transformers` | Steerable |\n| OpenAI | `from_openai()` | `OpenAI` | BlackBox |\n| Anthropic | `from_anthropic()` | `Anthropic` | BlackBox |\n| Google Gemini | `from_gemini()` | `Gemini` | BlackBox |\n| Ollama | `from_ollama()` | `Ollama` | BlackBox |\n| llama.cpp | `from_llamacpp()` | `Llamacpp` | Steerable |\n| MLX-LM | `from_mlxlm()` | `MlxLm` | Steerable |\n| vLLM | `from_vllm()` | `VLLM` | Steerable |\n| SGLang | `from_sglang()` | `SGLang` | Steerable |\n\nSource: [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n\n## FSM Compilation Pipeline\n\nThe FSM (Finite State Machine) compilation is the core mechanism that enables structured generation for steerable models.\n\n```mermaid\ngraph LR\n A[\"Python Type
(Pydantic, Literal, etc.)\"] --> B[\"JSON Schema\"]\n B --> C[\"Regex Pattern\"]\n C --> D[\"FSM
(via interegular)\"]\n D --> E[\"Token Mask\"]\n \n style A fill:#e1f5ff\n style E fill:#fff3e1\n```\n\n### Type System Transformations\n\nThe type system in `outlines/types/dsl.py` handles the conversion pipeline:\n\n1. **Python Types → JSON Schema**: Pydantic models and Python types are converted to JSON Schema\n2. **JSON Schema → Regex**: Complex types are converted to regex patterns\n3. **Regex → FSM**: The `outlines-core` library (using `interegular`) compiles regex to finite state machines\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Key Design Decisions\n\n### 1. FSM-Based Constraints\n\nFor local models where logits are accessible, constraints compile to finite state machines that track valid next tokens. The FSM maintains a current state and can determine, for any given state, which tokens are valid next tokens.\n\nThis approach provides:\n- **Complete coverage**: All valid continuations are allowed, all invalid are blocked\n- **Efficiency**: State transitions are O(1) lookup\n- **Correctness**: Guarantees well-formed outputs matching the schema\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 2. Token-Level Control\n\nConstraints apply at the token level, not the character level. This is critical because LLMs generate text token-by-token, and constraining at the character level would be both inefficient and potentially incorrect.\n\n```mermaid\ngraph TD\n A[\"Token 1: 'Hello'\"] --> B[\"Token 2: 'World'\"]\n B --> C[\"Token 3: '!'\"]\n \n subgraph FSM_State\n D[\"Current State: q3\"]\n E[\"Valid Tokens: [END, '!', '.']\"]\n end\n \n D --> E\n```\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 3. Lazy Compilation\n\nFSM compilation is deferred until first use and the resulting FSM is cached persistently. This avoids expensive compilation overhead on module import or model loading, and allows the system to handle dynamic type specifications efficiently.\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 4. Type-Driven API\n\nPython types are the primary interface for specifying constraints, aligning with how developers already specify data structures in Python code.\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass Review(BaseModel):\n sentiment: Literal[\"positive\", \"negative\", \"neutral\"]\n confidence: float\n\nresult = model(\"I love this product!\", Review)\n```\n\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Exception Handling Architecture\n\nOutlines defines a hierarchical exception system for consistent error handling across providers.\n\n```mermaid\ngraph TD\n A[\"Exception\"] --> B[\"OutlinesError\"]\n B --> C[\"APIError\"]\n \n C --> D[\"AuthenticationError\"]\n C --> E[\"PermissionDeniedError\"]\n C --> F[\"NotFoundError\"]\n C --> G[\"RateLimitError\"]\n C --> H[\"BadRequestError\"]\n C --> I[\"ServerError\"]\n \n B --> J[\"ProviderResponseError\"]\n B --> K[\"GenerationError\"]\n```\n\nAll public exceptions inherit from `OutlinesError` → `APIError` (for provider errors). The `normalize_provider_exception` function converts raw provider SDK exceptions into appropriate Outlines types.\n\nSource: [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## Generation Workflow\n\nThe following diagram illustrates the complete generation workflow for a structured output request:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Model\n participant Generator\n participant TypeSystem\n participant FSM\n participant Guide\n participant LogitsProcessor\n \n User->>Model: model(prompt, OutputType)\n Model->>Generator: create Generator(model, OutputType)\n Generator->>TypeSystem: convert(OutputType)\n TypeSystem->>FSM: compile to FSM\n Note over FSM: FSM cached after first use\n \n loop For each token\n Model->>LogitsProcessor: logits\n LogitsProcessor->>Guide: get valid tokens\n Guide->>LogitsProcessor: token mask\n LogitsProcessor->>Model: masked logits\n Model->>Guide: next token\n Guide->>FSM: transition state\n end\n \n Generator->>Model: final output\n Model-->>User: structured result\n```\n\nSource: [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Backend System\n\nThe backend system provides abstraction for different inference engines used with steerable models.\n\n```python\n# Backend selection via generator\ngenerator = Generator(model, OutputType, backend=\"transformers\")\n\n# Or via direct model call\nresult = model(prompt, OutputType, backend=\"vllm\")\n```\n\nAvailable backends for steerable models include:\n\n| Backend | Description |\n|---------|-------------|\n| `transformers` | Hugging Face Transformers library |\n| `vllm` | vLLM inference engine |\n| `sglang` | SGLang runtime |\n| `llamacpp` | llama.cpp inference |\n\nSource: [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Version 1 Interface Changes\n\nOutlines v1 introduced significant architectural changes to the model interface:\n\n### Before (v0)\n```python\nfrom outlines import generate, models\n\nmodel = models.openai(\"gpt-4o\")\ngenerator = generate.json(model, Character)\nresult = generator(\"Create a character\")\n```\n\n### After (v1)\n```python\nfrom outlines import from_openai\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nKey changes:\n- Models can now be called directly with prompt and output type\n- All models have a `stream()` method callable by users\n- `Generator` class provides reusable generation with caching\n- `Application` class replaces deprecated `Function` class for templated generation\n\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Documentation Architecture\n\nThe project uses MkDocs with automatic API reference generation:\n\n```mermaid\ngraph TD\n A[\"scripts/gen_ref_pages.py\"] --> B[\"mkdocs.yml\"]\n B --> C[\"mkdocs-gen-files\"]\n C --> D[\"API Reference Pages\"]\n \n subgraph \"Documentation Structure\"\n E[\"docs/guide/\"] --> F[\"User Guides\"]\n G[\"docs/features/\"] --> H[\"Feature Documentation\"]\n I[\"api_reference/\"] --> J[\"Auto-generated API Docs\"]\n end\n```\n\nSource: [scripts/gen_ref_pages.py](https://github.com/dottxt-ai/outlines/blob/main/scripts/gen_ref_pages.py)\nSource: [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n\n---\n\n\n\n## Core Concepts\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture), [Output Types Overview](#page-output-types), [Structured Generation Backends](#page-backends)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n \n\n# Core Concepts\n\nOutlines is a structured text generation library that guarantees type-safe, constrained outputs from Large Language Models (LLMs). Rather than post-processing model outputs with fragile parsing logic, Outlines integrates constraint enforcement directly into the generation process, ensuring outputs conform to specified structures from the moment generation begins.\n\n## Architecture Overview\n\nOutlines employs a layered architecture that transforms high-level type specifications into low-level token masking operations. The system bridges the gap between Python type annotations and the token-level mechanics of language model inference.\n\n```mermaid\ngraph TD\n A[User API
outlines.models] --> B[Generator Classes
SteerableGenerator
BlackBoxGenerator]\n B --> C[Type System
Pydantic → JsonSchema → Regex]\n C --> D[FSM Compilation
outlines-core
regex → FSM via interegular]\n D --> E[Guide System
processors/guide.py
FSM state management]\n E --> F[Logits Processing
processors/structured.py
token masking]\n F --> G[Model Providers
transformers
OpenAI
Anthropic
etc.]\n```\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Layer Stack\n\n### 1. User API Layer (`outlines.models`)\n\nThe topmost layer provides the primary interface for developers. Users instantiate a model using provider-specific functions and call it directly with prompts and output types.\n\n**Source:** [llm.txt:architecture](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 2. Generator Classes\n\nTwo generator abstractions handle different model categories:\n\n| Generator Class | Model Type | Control Level | Constraint Application |\n|-----------------|------------|---------------|------------------------|\n| `SteerableGenerator` | Local models (transformers, llama.cpp) | Full logits control | FSM-based token masking |\n| `BlackBoxGenerator` | API models (OpenAI, Anthropic) | API-level constraints | Provider's native structured output |\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 3. Type System (`types/dsl.py`)\n\nThe type system transforms Python types into machine-processable constraints:\n\n```mermaid\ngraph LR\n A[Pydantic Models
BaseModel] --> B[JSON Schema]\n B --> C[Regex Pattern]\n C --> D[Finite State Machine]\n```\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 4. FSM Compilation (`outlines-core`)\n\nThe compilation layer converts regex patterns into finite state machines using the `interegular` library. This transformation enables efficient constraint checking at token boundaries.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 5. Guide System (`processors/guide.py`)\n\nThe guide system manages FSM state transitions during generation. It tracks which states are valid given the current token sequence and determines allowable next tokens.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 6. Logits Processing (`processors/structured.py`)\n\nFor steerable models, this layer applies token masking by setting probabilities of invalid tokens to negative infinity, ensuring they cannot be selected during sampling.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Key Design Decisions\n\n### FSM-Based Constraints\n\nFor local models where Outlines controls the sampling process, constraints compile to finite state machines. These FSMs track valid next tokens at each generation step, enabling efficient constraint enforcement without enumerating all possible sequences.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Provider Abstraction\n\nThe same constraint system works across different model providers:\n\n- **Local models**: Outlines controls sampling, applying FSM-based masking\n- **API models**: Outlines uses provider-native structured output support when available, or falls back to completion with validation\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Lazy Compilation\n\nFSM compilation occurs on first use and results are cached persistently. This approach avoids upfront compilation overhead while ensuring subsequent generations with the same type are fast.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Token-Level Control\n\nConstraints apply at the token level rather than the character level. This design choice ensures that the constraint system works correctly with subword tokenization schemes used by modern language models.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Type-Driven API\n\nPython types serve as the primary interface for specifying output constraints. This design choice provides:\n\n- Familiar syntax for Python developers\n- Static type checking support\n- Integration with Pydantic for complex validation\n- Support for Literal types, enums, and nested structures\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## Model Integration\n\n### Base Model Architecture\n\nThe `Model` base class defines the contract for all provider implementations. Concrete implementations inherit from this base and implement provider-specific input/output handling.\n\n```python\n# Simplified base class structure\nclass Model(ABC):\n @abstractmethod\n def __call__(self, prompt, output_type):\n pass\n \n @abstractmethod\n def stream(self, prompt, output_type):\n pass\n```\n\n**Source:** [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n### Supported Providers\n\nOutlines provides integrations for multiple model providers:\n\n| Provider | Function | Control Type |\n|----------|----------|--------------|\n| OpenAI | `from_openai()` | BlackBox |\n| Anthropic | `from_anthropic()` | BlackBox |\n| Google Gemini | `from_gemini()` | BlackBox |\n| Transformers | `from_transformers()` | Steerable |\n| Ollama | `from_ollama()` | Steerable/BlackBox |\n| vLLM | `from_vllm()` | Steerable |\n| SGLang | `from_sglang()` | Steerable |\n| Llama.cpp | `from_llamacpp()` | Steerable |\n\n**Source:** [mkdocs.yml:navigation](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n\n### Gemini Integration Example\n\n```python\nfrom outlines import from_gemini\n\nclient = Client() # google.genai.Client\nmodel = from_gemini(client, model_name=\"gemini-pro\")\nresult = model(\"What is 2 + 2?\", int) # Returns 4\n```\n\n**Source:** [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n\n## Error Handling\n\n### Exception Hierarchy\n\nOutlines defines a comprehensive exception hierarchy for structured error handling:\n\n```\nOutlinesError (base)\n├── APIError (provider API errors)\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ └── ServerError\n├── APITimeoutError\n├── APIConnectionError\n├── ProviderResponseError\n└── GenerationError\n```\n\n**Source:** [outlines/exceptions.py:outlines-exception-hierarchy](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n### Exception Normalization\n\nThe `normalize_provider_exception` function converts raw provider SDK exceptions into appropriate Outlines types, preserving original exceptions for debugging:\n\n```python\ndef normalize_provider_exception(\n exception: Exception, \n provider: Optional[str] = None\n) -> OutlinesError\n```\n\n**Source:** [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## Output Types\n\n### Basic Python Types\n\nOutlines supports primitive Python types as output specifications:\n\n| Type | Generated Output |\n|------|------------------|\n| `int` | Integer numbers |\n| `float` | Decimal numbers |\n| `bool` | True/False |\n| `str` | Arbitrary strings |\n\n**Source:** [README.md:quickstart](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Literal Types\n\nFor constrained choices, `Literal` types specify exact valid outputs:\n\n```python\nfrom typing import Literal\n\nresult = model(\"Is this positive or negative?\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Pydantic Models\n\nComplex nested structures use Pydantic for specification:\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n```\n\n**Source:** [README.md:complex-structures](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Regex Patterns\n\nThe `Regex` type constrains outputs to match specific patterns:\n\n```python\nfrom outlines.types import Regex\n\nphone_number = model(\"Contact:\", Regex(r\"\\d{3}-\\d{3}-\\d{4}\"))\n```\n\n**Source:** [outlines/release_note.md:regex-dsl](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n### JSON Schema\n\nFor language-agnostic type definitions, `JsonSchema` accepts raw JSON Schema strings:\n\n```python\nfrom outlines.types import JsonSchema\n\nschema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2?\", JsonSchema(schema))\n```\n\n**Source:** [outlines/release_note.md:regex-dsl](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Generator Pattern\n\nThe `Generator` class encapsulates reusable generation with a fixed output type:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(...)\ngenerator = Generator(model, Character)\n\n# Reuse without recompiling the output type\nresult1 = generator(\"Create a male character\", {\"gender\": \"male\"})\nresult2 = generator(\"Create a female character\", {\"gender\": \"female\"})\n```\n\n**Source:** [outlines/release_note.md:generator-constructor](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Application Pattern\n\nThe `Application` class combines templates with structured output types:\n\n```python\nfrom outlines import Application, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\n\nresult = app(model, {\"gender\": \"female\"})\n```\n\n**Source:** [outlines/release_note.md:application-class](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## The Outlines Philosophy\n\nOutlines mirrors Python's type system philosophy: specify what you want, and the system ensures it. Rather than validating and parsing outputs after generation, Outlines guarantees structurally valid outputs from the start.\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Design Principles\n\n1. **Constraint at generation time**: Validity is enforced during token selection, not after\n2. **Fail fast**: Invalid outputs are impossible by construction\n3. **Provider independence**: Same API works across all supported models\n4. **Type familiarity**: Use standard Python types and Pydantic models\n\n**Source:** [README.md:why-outlines](https://github.com/dottext-ai/outlines/blob/main/README.md)\n\n---\n\n\n\n## Structured Generation Backends\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n- [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n- [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n- [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n- [docs/features/advanced/backends.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/advanced/backends.md)\n \n\n# Structured Generation Backends\n\nStructured Generation Backends are the underlying engine components in Outlines that handle the compilation of structured constraints (such as JSON schemas and regular expressions) into efficient token-level generation guides. These backends abstract away the complexity of constraint compilation, providing a unified interface for steering language model outputs while allowing users to choose the most appropriate implementation for their use case.\n\n## Architecture Overview\n\nOutlines supports multiple backend implementations for structured generation, each with different trade-offs in terms of performance, memory usage, and feature support. The backend system follows a pluggable architecture where users can select or let Outlines choose the optimal backend automatically.\n\n```mermaid\ngraph TD\n User[User Code] --> API[Outlines API]\n API --> Backends[Backend Selection]\n Backends --> Core[OutlinesCore]\n Backends --> XGrammar[XGrammar]\n Backends --> LLGuidance[LLGuidance]\n \n Core --> FSM[FSM Compilation]\n XGrammar --> XG_Engine[XGrammar Engine]\n LLGuidance --> LL_Engine[LLGuidance Engine]\n \n FSM --> Guide[Generation Guide]\n XG_Engine --> Guide\n LL_Engine --> Guide\n \n Guide --> Tokens[Token Masking]\n Tokens --> Model[Language Model]\n Model --> Output[Structured Output]\n```\n\nThe backend system sits between the high-level Outlines API and the underlying language model, transforming structural constraints into actionable token-level guidance during generation. Source: [outlines/backends/__init__.py:1-60](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Available Backends\n\nOutlines provides three main backend implementations for structured generation, each optimized for different scenarios.\n\n| Backend | Module | Description |\n|---------|--------|-------------|\n| **OutlinesCore** | `outlines_core` | Default backend using the interegular library for FSM compilation |\n| **XGrammar** | `xgrammar` | Optimized backend using the xgrammar library for faster compilation |\n| **LLGuidance** | `llguidance` | Specialized backend using llguidance for high-performance generation |\n\nSource: [outlines/backends/__init__.py:20-30](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### OutlinesCore Backend\n\nThe OutlinesCore backend is the default implementation that uses the `interegular` library to compile regular expressions and JSON schemas into Finite State Machines (FSMs). This backend provides comprehensive support for all Outlines features and serves as the reference implementation.\n\nKey characteristics:\n- Pure Python implementation using interegular for regex parsing\n- Persistent caching of compiled FSMs\n- Full support for JSON schemas and regex constraints\n- Memory-efficient for moderate-sized schemas\n\nThe backend converts structured constraints through the following pipeline:\n1. Parse the JSON schema or regex pattern\n2. Compile to an intermediate FSM representation using interegular\n3. Optimize the FSM for token-level generation\n4. Cache the compiled result for reuse\n\nSource: [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n\n### XGrammar Backend\n\nThe XGrammar backend provides an optimized implementation that leverages the xgrammar library for faster constraint compilation. This backend is particularly useful for applications requiring quick iteration cycles where compilation speed matters.\n\nKey characteristics:\n- Faster compilation times compared to OutlinesCore\n- Optimized token masking operations\n- Good balance between performance and memory usage\n- Requires xgrammar as an additional dependency\n\nSource: [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n\n### LLGuidance Backend\n\nThe LLGuidance backend uses the llguidance library to provide high-performance structured generation. This backend is designed for production workloads where generation speed is critical.\n\nKey characteristics:\n- Maximum generation throughput\n- Low-latency token selection\n- Specialized for constrained generation scenarios\n- Requires llguidance as an additional dependency\n\nSource: [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n\n## Backend Selection\n\nOutlines provides two mechanisms for backend selection: automatic default selection and explicit user specification.\n\n### Default Backend Configuration\n\nWhen no backend is explicitly specified, Outlines uses the default backends defined in the configuration:\n\n| Constraint Type | Default Backend |\n|----------------|-----------------|\n| JSON Schema | `outlines_core` |\n| Regex | `outlines_core` |\n\nSource: [outlines/backends/__init__.py:25-28](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### Explicit Backend Selection\n\nUsers can specify a backend explicitly using the `backend` parameter when calling model generation methods:\n\n```python\nimport outlines\nfrom pydantic import BaseModel\n\nclass Person(BaseModel):\n name: str\n age: int\n\n# Use specific backend\nresult = model(\"Create a person\", Person, backend=\"xgrammar\")\n```\n\nBackend names are case-insensitive and map to the following implementations:\n\n- `\"outlines_core\"` or `\"outlinescore\"`: OutlinesCore backend\n- `\"xgrammar\"`: XGrammar backend\n- `\"llguidance\"`: LLGuidance backend\n\nSource: [outlines/backends/__init__.py:55-58](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Backend Factory Functions\n\nThe backend system provides factory functions that create the appropriate logits processor based on the constraint type and selected backend.\n\n### JSON Schema Logits Processor\n\nThe `get_json_schema_logits_processor` function creates a logits processor for JSON schema constraints:\n\n```python\ndef get_json_schema_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n json_schema: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a JSON schema.\n \n Parameters\n ----------\n backend_name : str | None\n The name of the backend to use.\n model : Model\n The Outlines model of the user.\n json_schema : str\n The JSON schema to create a logits processor from.\n \n Returns\n -------\n LogitsProcessorType\n The logits processor.\n \"\"\"\n backend = _get_backend(\n backend_name or JSON_SCHEMA_DEFAULT_BACKEND,\n model,\n )\n return backend.get_json_schema_logits_processor(json_schema)\n```\n\nSource: [outlines/backends/__init__.py:58-85](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### Regex Logits Processor\n\nThe `get_regex_logits_processor` function creates a logits processor for regex constraints:\n\n```python\ndef get_regex_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n regex: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a regex.\n \n Parameters\n ----------\n backend_name : str | None\n The name of the backend to use.\n model : Model\n The Outlines model of the user.\n regex : str\n The regex to create a logits processor from.\n \n Returns\n -------\n LogitsProcessorType\n The logits processor.\n \"\"\"\n backend = _get_backend(\n backend_name or REGEX_DEFAULT_BACKEND,\n model,\n )\n return backend.get_regex_logits_processor(regex)\n```\n\nSource: [outlines/backends/__init__.py:87-115](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Backend Interface\n\nAll backends implement a common interface defined in the base backend class. This ensures consistent behavior across different implementations.\n\n### Base Backend Methods\n\nEach backend must implement the following methods:\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `get_json_schema_logits_processor(json_schema)` | Create processor for JSON schema constraints | `LogitsProcessorType` |\n| `get_regex_logits_processor(regex)` | Create processor for regex constraints | `LogitsProcessorType` |\n\nSource: [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n\n### Backend Registry\n\nThe backend system uses a registry pattern to manage available implementations:\n\n```python\nBACKENDS = {\n \"outlines_core\": OutlinesCoreBackend,\n \"xgrammar\": XGrammarBackend,\n \"llguidance\": LLGuidanceBackend,\n}\n\ndef _get_backend(backend_name: str, model: SteerableModel):\n \"\"\"Get a backend instance by name.\"\"\"\n if backend_name == \"outlines_core\":\n return OutlinesCoreBackend(model)\n elif backend_name == \"xgrammar\":\n return XGrammarBackend(model)\n elif backend_name == \"llguidance\":\n return LLGuidanceBackend(model)\n else:\n raise ValueError(f\"Backend {backend_name} not supported\")\n```\n\nSource: [outlines/backends/__init__.py:30-45](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Integration with Model Classes\n\nBackends are invoked through the Generator class and model calling interfaces. When a user specifies an output type, the appropriate backend is selected to create a logits processor that guides the generation.\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Model as Model Class\n participant Generator as Generator\n participant Backend as Backend Selection\n participant Processor as Logits Processor\n \n User->>Model: model(prompt, output_type, backend=\"xgrammar\")\n Model->>Generator: Generator(model, output_type, backend)\n Generator->>Backend: _get_backend(backend_name, model)\n Backend->>Processor: get_json_schema_logits_processor(json_schema)\n Processor-->>Generator: logits_processor\n Generator-->>User: response\n```\n\nThe `stream` and `batch` methods on model classes also support backend specification:\n\n```python\n# Direct model calling with backend\nresult = model(\"prompt\", MySchema, backend=\"llguidance\")\n\n# Streaming with backend\nasync for chunk in model.stream(\"prompt\", MySchema, backend=\"xgrammar\"):\n print(chunk)\n\n# Batch processing with backend\nresults = await model.batch([\"prompt1\", \"prompt2\"], MySchema, backend=\"llguidance\")\n```\n\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Error Handling\n\nThe backend system provides clear error messages when an unsupported backend is requested:\n\n```python\nraise ValueError(f\"Backend {backend_name} not supported\")\n```\n\nThis ensures users receive actionable feedback when misconfiguring the backend selection.\n\nSource: [outlines/backends/__init__.py:43-45](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Choosing a Backend\n\nThe following flowchart helps users select the appropriate backend for their use case:\n\n```mermaid\ngraph TD\n Start[Select Backend] --> NeedSpeed{Need Maximum
Generation Speed?}\n \n NeedSpeed -->|Yes| IsLLG{Available:
llguidance?}\n NeedSpeed -->|No| NeedCompile{Need Fast
Compilation?}\n \n IsLLG -->|Yes| UseLLG[Use llguidance]\n IsLLG -->|No| NeedCompile\n \n NeedCompile -->|Yes| IsXG{Available:
xgrammar?}\n NeedCompile -->|No| UseCore[Use OutlinesCore
Default]\n \n IsXG -->|Yes| UseXG[Use xgrammar]\n IsXG -->|No| UseCore\n```\n\n### Backend Selection Guidelines\n\n| Use Case | Recommended Backend |\n|----------|--------------------|\n| Development and testing | OutlinesCore (default) |\n| Fast iteration, quick schema changes | XGrammar |\n| Production, high-throughput requirements | LLGuidance |\n| Memory-constrained environments | OutlinesCore |\n| Latency-critical applications | LLGuidance |\n\n## Dependencies\n\nBackends may require additional Python packages beyond the core Outlines installation:\n\n| Backend | Required Package | Installation |\n|---------|-----------------|--------------|\n| OutlinesCore | `outlines-core` | Included with `pip install outlines` |\n| XGrammar | `xgrammar` | `pip install xgrammar` |\n| LLGuidance | `llguidance` | `pip install llguidance` |\n\n## Configuration Integration\n\nBackends can be configured globally through Outlines configuration files or environment variables. The backend selection is determined in the following order of precedence:\n\n1. Explicit `backend` parameter in the API call (highest priority)\n2. Default backend for the constraint type (lowest priority)\n\nThis allows users to set system-wide defaults while maintaining the flexibility to override per-call.\n\n---\n\n\n\n## Output Types Overview\n\n### Related Pages\n\nRelated topics: [JSON Schema and Pydantic Support](#page-json-schemas), [Regex Patterns](#page-regex-patterns)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/__init__.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n \n\n# Output Types Overview\n\nOutlines provides a comprehensive type system for structured generation with Large Language Models (LLMs). Output types define the expected structure of generated text, and Outlines ensures that generated outputs match these specifications exactly during inference.\n\n## Purpose and Scope\n\nOutput types in Outlines serve as the primary interface for specifying constraints on LLM outputs. Rather than attempting to parse and fix invalid outputs after generation, Outlines enforces structure during the generation process itself. This approach eliminates fragile parsing logic and guarantees valid outputs on the first attempt.\n\nThe type system supports various complexity levels:\n\n| Type Category | Examples | Use Case |\n|---------------|----------|----------|\n| Basic Python | `int`, `float`, `str` | Simple values |\n| Literal Types | `Literal[\"Yes\", \"No\"]` | Enumerated choices |\n| Pydantic Models | `BaseModel` subclasses | Complex nested structures |\n| Regex Patterns | `Regex(...)`, `JsonSchema(...)` | Custom format constraints |\n| Context-Free Grammars | `CFG(...)` | Formal language definitions |\n\nSource: [README.md:1-20]()\n\n## Architecture\n\n### Type Conversion Pipeline\n\nOutlines converts output types into finite state machines (FSMs) that guide token selection during generation. This conversion follows a layered approach:\n\n```mermaid\ngraph TD\n A[Python Type / Pydantic Model] --> B[JSON Schema]\n B --> C[Regex Pattern]\n C --> D[FSM / State Machine]\n D --> E[Token Masking Guide]\n E --> F[Constrained Generation]\n \n G[DSL Terms] --> C\n H[CFG Grammar] --> C\n```\n\nThe type system handles three primary conversion pathways:\n\n1. **Python Types to Terms**: Basic types (`int`, `str`, `float`) and `Literal` types convert to intermediate `Term` representations\n2. **Pydantic Models to JSON Schema**: Complex models generate JSON Schema definitions\n3. **Terms to Regex**: All intermediate representations ultimately convert to regex patterns\n\nSource: [outlines/types/dsl.py:1-30]()\n\n### Core Components\n\n| Component | File Location | Responsibility |\n|-----------|---------------|----------------|\n| Term Classes | `outlines/types/dsl.py` | Define regex DSL elements |\n| JSON Schema Utilities | `outlines/types/json_schema_utils.py` | Pydantic to schema conversion |\n| Type Adapters | `outlines/types/utils.py` | Type introspection helpers |\n| FSM Compilation | `outlines-core` package | Regex to finite state machines |\n\nSource: [llm.txt:1-50]()\n\n## Basic Python Types\n\nOutlines supports native Python types as output specifications. These types are automatically converted to appropriate constraints.\n\n### Supported Types\n\n```python\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Integer output\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n\n# String output (constrained format)\nname = model(\"Generate a valid email address\", str)\n```\n\n| Type | Constraint Applied |\n|------|-------------------|\n| `int` | Matches integer patterns |\n| `float` | Matches decimal numbers |\n| `str` | General text with type hints |\n\nSource: [README.md:45-60]()\n\n### Literal Types\n\n`Literal` types define exact enumerated values the model can output:\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\nThis approach is ideal for classification tasks, yes/no questions, and any scenario requiring outputs from a fixed set of options.\n\nSource: [README.md:50-55]()\n\n## Pydantic Models\n\nFor complex structured outputs, Pydantic models provide a declarative interface to define nested schemas with validation.\n\n### Defining Models\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nreview = model(\"Review the latest iPhone\", ProductReview)\n```\n\n### Model Conversion Process\n\n```mermaid\ngraph LR\n A[Pydantic BaseModel] --> B[JSON Schema]\n B --> C[Regex via interegular]\n C --> D[FSM]\n D --> E[Guided Generation]\n \n F[TypeAdapter] --> A\n G[GetJsonSchemaHandler] --> B\n```\n\nThe conversion process uses Pydantic's schema generation hooks:\n\n```python\nfrom pydantic import BaseModel, GetCoreSchemaHandler\nfrom pydantic.json_schema import JsonSchemaValue\nfrom pydantic_core import core_schema as cs\n\nclass CustomType(BaseModel):\n @classmethod\n def __get_pydantic_core_schema__(\n cls, \n source_type: Any, \n handler: GetCoreSchemaHandler\n ) -> cs.CoreSchema:\n return cs.string_schema(\n pattern=r\"^[A-Z]{2}\\d{4}$\" # Format: XX0000\n )\n```\n\nSource: [outlines/types/dsl.py:40-80]()\n\n## Regular Expression DSL\n\nThe Regex DSL provides fine-grained control over output formats through composable term classes.\n\n### Term Classes\n\n| Term Class | Description | Example |\n|------------|-------------|---------|\n| `Regex` | Base regex wrapper | `Regex(r\"\\d{3}-\\d{4}\")` |\n| `String` | Literal string match | `String(\"yes\")` |\n| `Integer` | Integer numbers | `Integer()` |\n| `Alternatives` | Choice between patterns | `either(pattern1, pattern2)` |\n| `KleeneStar` | Zero or more repetitions | `repeat(pattern)` |\n| `Optional` | Optional pattern | `optional(pattern)` |\n\nSource: [outlines/types/dsl.py:20-60]()\n\n### Building Complex Patterns\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# Phone number pattern\nphone = either(\n Regex(r\"\\d{3}-\\d{3}-\\d{4}\"),\n Regex(r\"\\(\\d{3}\\) \\d{3}-\\d{4}\")\n)\n\n# Complex format with optional parts\ndate_format = Sequence(\n integer(), # Year\n literal(\"-\"),\n at_least(integer(), 1), # At least one month\n optional(literal(\"-\") + at_least(integer(), 1)) # Optional day\n)\n```\n\n### Term Functions\n\nThe DSL includes utility functions for pattern composition:\n\n- `either(*terms)`: Match any one of multiple terms\n- `optional(term)`: Make a pattern optional\n- `at_least(term, n)`: Require at least n repetitions\n- `one_of(*choices)`: Synonym for `either`\n- `literal(text)`: Match exact text\n\nSource: [outlines/release_note.md:40-80]()\n\n## JsonSchema Type\n\nThe `JsonSchema` type allows direct use of JSON Schema definitions for complex validation:\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '''\n{\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\"type\": \"number\"},\n \"confidence\": {\"type\": \"number\", \"minimum\": 0, \"maximum\": 1}\n },\n \"required\": [\"answer\"]\n}\n'''\n\nresult = model(\"What's 2 + 2? Respond in JSON.\", JsonSchema(json_schema))\n```\n\nThis approach is useful when:\n\n- Migrating existing JSON Schema definitions\n- Working with API specifications (OpenAPI, etc.)\n- Defining schemas separately from code\n\nSource: [outlines/release_note.md:50-65]()\n\n## Context-Free Grammars\n\nOutlines supports Context-Free Grammars (CFG) for formal language generation:\n\n```python\nfrom outlines.types import CFG\n\ngrammar = CFG(\"\"\"\n expression ::= number op number\n op ::= \"+\" | \"-\" | \"*\" | \"/\"\n number ::= [0-9]+\n\"\"\")\n\nmath_result = model(\"Calculate 5 + 3\", grammar)\n```\n\nCFGs are particularly valuable for:\n\n- Programming language generation\n- Mathematical expression evaluation\n- Structured domain-specific languages\n\nSource: [outlines/release_note.md:60-70]()\n\n## Union Types\n\nUnion types enable conditional or alternative output structures:\n\n```python\nfrom typing import Union\n\nclass SuccessResponse(BaseModel):\n data: str\n timestamp: str\n\nUnknownResponse = Literal[\"I don't know\", \"Unable to determine\"]\n\nResponse = Union[SuccessResponse, UnknownResponse]\n\nresult = model(\"What is the capital of France?\", Response)\n```\n\n### Handling Incomplete Data\n\nUnion types excel at scenarios where partial information is acceptable:\n\n```python\nclass EventInfo(BaseModel):\n name: str\n date: str\n location: str\n\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\nresult = model(\n \"Extract event details: 'Join us for the meeting next week!'\",\n EventResponse\n)\n```\n\nSource: [README.md:100-120]()\n\n## Generator Integration\n\nThe `Generator` class encapsulates output types for reusable constrained generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n species: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ncharacter_generator = Generator(model, Character)\nresult = character_generator(\"Create a fantasy character\")\n```\n\nBenefits of using generators:\n\n| Feature | Benefit |\n|---------|---------|\n| Cached compilation | FSM compiled once, reused across calls |\n| Type inference | Output type specified at construction |\n| Consistent behavior | Same constraints applied to all generations |\n\nSource: [outlines/release_note.md:20-40]()\n\n## Type System Internals\n\n### Conversion Pipeline Details\n\n```mermaid\ngraph TD\n subgraph \"Type Definition\"\n A[Pydantic / Python Type] --> B[Term Representation]\n B --> C[Regex Pattern]\n end\n \n subgraph \"Compilation\"\n C --> D[FSM via interegular]\n D --> E[Cached FSM]\n end\n \n subgraph \"Generation\"\n E --> F[Guide Processor]\n F --> G[Token Masking]\n G --> H[Constrained Sampling]\n end\n```\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `outlines/types/__init__.py` | Public API exports |\n| `outlines/types/dsl.py` | Term classes and regex DSL |\n| `outlines/types/json_schema_utils.py` | Schema conversion utilities |\n| `outlines/types/utils.py` | Type introspection helpers |\n\nSource: [llm.txt:30-60]()\n\n## Best Practices\n\n### Choosing Output Types\n\n1. **Use Literal types** for classification and yes/no responses\n2. **Use Python primitives** (`int`, `float`) for simple numerical outputs\n3. **Use Pydantic models** for complex, nested structures\n4. **Use Regex DSL** when you need precise format control\n5. **Use CFG** for formal language generation\n\n### Performance Considerations\n\n| Complexity | Compilation Time | Runtime Overhead |\n|------------|------------------|------------------|\n| Literal types | Minimal | Negligible |\n| Simple regex | Low | Low |\n| Pydantic models | Moderate | Moderate |\n| Complex grammars | Higher | Higher |\n\nFSM compilation happens once on first use and is cached for subsequent calls, minimizing repeated overhead.\n\nSource: [llm.txt:40-50]()\n\n## Summary\n\nOutlines' output types system provides a unified, Pythonic interface for structured generation:\n\n- **Type-driven API**: Python types, Pydantic models, and custom DSLs\n- **Guaranteed validity**: Constraints enforced during generation, not after\n- **Flexible composition**: Union types, regex patterns, and grammars\n- **Performance optimized**: FSM caching and lazy compilation\n\nThe type system transforms high-level type specifications into optimized finite state machines, enabling reliable structured generation across diverse LLM providers.\n\n---\n\n\n\n## JSON Schema and Pydantic Support\n\n### Related Pages\n\nRelated topics: [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/types/json_schema_utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/json_schema_utils.py)\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/models/vllm_offline.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/vllm_offline.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n \n\n# JSON Schema and Pydantic Support\n\nOutlines provides robust support for JSON Schema and Pydantic models as first-class output type specifications. This enables developers to define complex structured output schemas using familiar Python type annotations, which are then compiled into efficient finite state machines (FSMs) for guided text generation.\n\n## Overview\n\nThe JSON Schema and Pydantic support in Outlines serves three primary purposes:\n\n1. **Type Definition** - Allows users to define output structures using Python-native type hints\n2. **Schema Conversion** - Provides bidirectional conversion between JSON Schema, Pydantic, TypedDict, and dataclass representations\n3. **Constraint Compilation** - Transforms schema definitions into regular expressions and FSMs for guided generation\n\nSource: [outlines/types/dsl.py:1-30]()\n\n## Architecture\n\n### Layer Stack for Structured Output\n\n```mermaid\ngraph TD\n A[User API: Pydantic Model / JSON Schema] --> B[Type System: python_types_to_terms]\n B --> C[JsonSchema Term / CFG Term]\n C --> D[Regex Compilation: to_regex]\n D --> E[FSM Generation via outlines-core]\n E --> F[Logits Processor: Token Masking]\n F --> G[Model Providers]\n \n H[Pydantic / TypedDict / Dataclass] -->|json_schema_dict_to_pydantic| B\n I[JSON Schema String] -->|JsonSchema class| B\n```\n\nThe type system in Outlines follows a layered architecture where Python types are progressively converted into machine-executable constraints:\n\n| Layer | Component | Responsibility |\n|-------|-----------|----------------|\n| User API | Pydantic models, JSON Schema | Define desired output structure |\n| Type System | `python_types_to_terms` | Convert Python types to Term instances |\n| Schema Representation | `JsonSchema`, `CFG` classes | Represent constraints as Terms |\n| Regex Compilation | `to_regex` | Transform Terms to regular expressions |\n| FSM Generation | outlines-core (interegular) | Convert regex to finite state machine |\n| Generation Control | Logits Processors | Mask invalid tokens during generation |\n\nSource: [outlines/types/dsl.py:46-80]()\n\n## JsonSchema Class\n\nThe `JsonSchema` class is the core abstraction for representing JSON Schema-based output types.\n\n### Class Definition\n\n```python\nclass JsonSchema(Term):\n \"\"\"Represents a JSON Schema constraint for structured generation.\"\"\"\n \n def __init__(self, schema: Union[str, dict], whitespace_pattern: Optional[str] = None):\n \"\"\"\n Args:\n schema: JSON Schema as string or dict\n whitespace_pattern: Optional regex for whitespace handling\n \"\"\"\n```\n\n### Key Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `to_format(target_type)` | Convert schema to Pydantic, TypedDict, or dataclass | Converted type or raises ValueError |\n| `from_file(path)` | Create JsonSchema from .json file | `JsonSchema` instance |\n| `_display_node()` | Get string representation | `str` |\n\nSource: [outlines/types/dsl.py:50-90]()\n\n### Schema Conversion\n\nThe `to_format` method supports converting JSON Schema to multiple Python type formats:\n\n```python\ndef to_format(self, target_types: List[str]) -> Any:\n \"\"\"Convert JSON Schema to target format(s).\n \n Supported targets: 'pydantic', 'typeddict', 'dataclass', 'str', 'dict'\n \"\"\"\n```\n\nThis method iterates through the requested target types and attempts conversion, returning the first successful result.\n\nSource: [outlines/types/dsl.py:55-80]()\n\n### Schema Validation and Comparison\n\n```python\ndef __eq__(self, other) -> bool:\n \"\"\"Compare two JsonSchema instances by parsing and comparing their contents.\"\"\"\n self_dict = json.loads(self.schema)\n other_dict = json.loads(other.schema)\n return self_dict == other_dict\n```\n\nSource: [outlines/types/dsl.py:100-108]()\n\n## JSON Schema Utilities\n\nThe `json_schema_utils.py` module provides bidirectional conversion between JSON Schema and Python type systems.\n\n### Schema Type Mapping\n\nJSON Schema types are mapped to Python types as follows:\n\n| JSON Schema Type | Python Type |\n|-----------------|-------------|\n| `string` | `str` |\n| `integer` | `int` |\n| `number` | `float` |\n| `boolean` | `bool` |\n| `array` | `List[item_type]` |\n| `object` | Pydantic / TypedDict / Dataclass |\n\nSource: [outlines/types/json_schema_utils.py:1-50]()\n\n### Conversion Functions\n\n#### json_schema_dict_to_pydantic\n\nConverts a JSON Schema dictionary to a Pydantic model:\n\n```python\ndef json_schema_dict_to_pydantic(\n schema: dict,\n name: Optional[str] = None\n) -> Type[BaseModel]:\n \"\"\"Convert JSON Schema dict to Pydantic BaseModel.\n \n Args:\n schema: JSON Schema dictionary\n name: Optional name for the model\n \n Returns:\n Pydantic BaseModel class\n \"\"\"\n```\n\n#### json_schema_dict_to_typeddict\n\nConverts JSON Schema to a TypedDict:\n\n```python\ndef json_schema_dict_to_typeddict(\n schema: dict,\n name: Optional[str] = None\n) -> _TypedDictMeta:\n \"\"\"Convert JSON Schema dict to TypedDict class.\"\"\"\n```\n\nThe conversion process:\n1. Extracts `required` fields from schema\n2. Maps `properties` to typed annotations\n3. Optional fields are wrapped with `Optional[]`\n4. Recursively handles nested objects\n\nSource: [outlines/types/json_schema_utils.py:80-120]()\n\n#### json_schema_dict_to_dataclass\n\nConverts JSON Schema to a dataclass:\n\n```python\ndef json_schema_dict_to_dataclass(\n schema: dict,\n name: Optional[str] = None\n) -> type:\n \"\"\"Convert JSON Schema dict to dataclass.\"\"\"\n```\n\n### schema_type_to_python\n\nRecursively converts JSON Schema type definitions to Python types:\n\n```python\ndef schema_type_to_python(\n schema: dict,\n caller_target_type: str = \"pydantic\"\n) -> Any:\n \"\"\"Convert JSON Schema type to Python type.\n \n Args:\n schema: JSON Schema dict or nested schema\n caller_target_type: Target format ('pydantic', 'typeddict', 'dataclass')\n \"\"\"\n```\n\nSource: [outlines/types/json_schema_utils.py:40-75]()\n\n## Backend Integration\n\nDifferent inference backends handle JSON Schema constraints through specialized logits processors.\n\n### Backend Selection\n\n```mermaid\ngraph LR\n A[Model Instance] --> B[_get_backend]\n B --> C{Backend Name}\n C -->|outlines_core| D[OutlinesCoreBackend]\n C -->|xgrammar| E[XGrammarBackend]\n C -->|llguidance| F[LLGuidanceBackend]\n \n D --> G[get_json_schema_logits_processor]\n E --> G\n F --> G\n```\n\nThe `get_json_schema_logits_processor` function creates the appropriate processor:\n\n```python\ndef get_json_schema_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n json_schema: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a JSON schema.\"\"\"\n backend = _get_backend(\n backend_name or JSON_SCHEMA_DEFAULT_BACKEND,\n model,\n )\n return backend.get_json_schema_logits_processor(json_schema)\n```\n\nSource: [outlines/backends/__init__.py:1-50]()\n\n### VLLM Offline Backend\n\nThe VLLM offline backend converts JsonSchema terms to vLLM's `GuidedDecodingParams`:\n\n```python\ndef _get_guided_decoding_params(self, output_type) -> dict:\n \"\"\"Convert output type to guided decoding parameters.\"\"\"\n if output_type is None:\n return {}\n\n term = python_types_to_terms(output_type)\n if isinstance(term, CFG):\n return {\"grammar\": term.definition}\n elif isinstance(term, JsonSchema):\n guided_decoding_params = {\"json\": json.loads(term.schema)}\n if term.whitespace_pattern:\n guided_decoding_params[\"whitespace_pattern\"] = term.whitespace_pattern\n return guided_decoding_params\n else:\n return {\"regex\": to_regex(term)}\n```\n\nSource: [outlines/models/vllm_offline.py:50-80]()\n\n## Usage Patterns\n\n### Basic Pydantic Model Usage\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nreview = model(\"Amazing laptop! Great battery life, fast processor.\", ProductReview)\n```\n\nSource: [README.md:1-50]()\n\n### Using json_schema Function\n\n```python\nimport outlines\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"},\n \"email\": {\"type\": \"string\", \"format\": \"email\"}\n },\n \"required\": [\"name\", \"email\"]\n}\n\nresult = model(\"Generate a user profile\", outlines.json_schema(schema))\n```\n\n### Union Types for Flexible Output\n\n```python\nfrom typing import Union, List, Literal\nfrom pydantic import BaseModel\n\nclass EventInfo(BaseModel):\n name: str\n date: str\n location: str\n\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\nresult = model(\"What event is mentioned?\", EventResponse)\n```\n\n## Type System Functions\n\nThe DSL module provides utility functions for type checking and conversion:\n\n### Type Check Functions\n\n| Function | Purpose |\n|----------|---------|\n| `is_int(t)` | Check if type is `int` |\n| `is_float(t)` | Check if type is `float` |\n| `is_str(t)` | Check if type is `str` |\n| `is_bool(t)` | Check if type is `bool` |\n| `is_datetime(t)` | Check if type is datetime |\n| `is_date(t)` | Check if type is date |\n| `is_time(t)` | Check if type is time |\n| `is_pydantic_model(t)` | Check if type is Pydantic BaseModel |\n| `is_enum(t)` | Check if type is Enum |\n| `is_literal(t)` | Check if type is Literal |\n| `is_union(t)` | Check if type is Union |\n| `is_typing_list(t)` | Check if type is List |\n| `is_typed_dict(t)` | Check if type is TypedDict |\n\nSource: [outlines/types/dsl.py:80-150]()\n\n### python_types_to_terms\n\nThe main conversion function that transforms Python types into Term instances:\n\n```python\ndef python_types_to_terms(\n output_type,\n whitespace_pattern: Optional[str] = None\n) -> Term:\n \"\"\"Convert Python types to Term instances for guided generation.\n \n Handles:\n - Primitive types (int, float, str, bool)\n - Collections (List, Dict, Tuple)\n - Pydantic models\n - Enums and Literals\n - Union types\n - JSON Schema strings\n - TypedDict and dataclasses\n \"\"\"\n```\n\nSource: [outlines/types/dsl.py:200-280]()\n\n## Error Handling\n\n### Schema Conversion Failures\n\nWhen schema conversion fails, Outlines provides informative warnings:\n\n```python\nexcept Exception as e: # pragma: no cover\n warnings.warn(\n f\"Cannot convert schema type {type(schema)} to {target_type}: {e}\"\n )\n continue\n```\n\nIf no valid conversion is found, a ValueError is raised:\n\n```python\nraise ValueError(\n f\"Cannot convert schema type {type(schema)} to any of the target \"\n f\"types {target_types}\"\n)\n```\n\nSource: [outlines/types/dsl.py:75-82]()\n\n## Best Practices\n\n1. **Use Pydantic for Complex Schemas** - Pydantic models provide validation and IDE autocomplete\n2. **Define Required Fields** - JSON Schema `required` array ensures critical fields are generated\n3. **Use Optional for Nullable Fields** - Mark non-required fields with `Optional[]` or `= None`\n4. **Leverage Union Types** - Return fallback values when data is incomplete\n5. **Cache Compiled FSMs** - Outlines caches compiled state machines for reuse\n\n## Related Components\n\n- **CFG Support** - Context-free grammar constraints for complex syntax\n- **Regex DSL** - Direct regular expression specifications\n- **Template System** - Jinja-based prompt templating\n- **Generator Class** - Reusable generator objects with pre-compiled constraints\n\n---\n\n\n\n## Regex Patterns\n\n### Related Pages\n\nRelated topics: [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [docs/features/utility/regex_dsl.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/utility/regex_dsl.md)\n- [docs/features/core/output_types.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/core/output_types.md)\n \n\n# Regex Patterns\n\nRegex patterns in Outlines provide a powerful Domain-Specific Language (DSL) for defining structured output constraints. The regex DSL allows developers to build complex pattern constraints by composing simple terms, which are then compiled into finite state machines (FSMs) that guide the language model's token generation process.\n\nThe core insight behind Outlines' regex support is that instead of generating text and hoping it matches a format, Outlines makes it impossible for the model to generate invalid outputs by masking invalid tokens during generation. Source: [llm.txt:1-10]()\n\n## Overview\n\nOutlines supports regex patterns at multiple levels of abstraction:\n\n1. **Direct Regex Patterns**: Use `Regex` class to define patterns that can be used as Pydantic field types\n2. **Regex DSL**: Compose complex patterns using term functions like `either`, `optional`, `at_least`, and integer/string helpers\n3. **JSON Schema Integration**: `JsonSchema` term accepts JSON schema strings and converts them to regex constraints\n4. **Context-Free Grammars**: `CFG` term provides grammar-based constraints for more complex languages\n\nSource: [outlines/release_note.md:1-20]()\n\n### Type Conversion Pipeline\n\nThe regex system follows a well-defined conversion pipeline:\n\n```\nPydantic Model / Python Type → Term DSL → Regex → FSM → Token Masking\n```\n\nThis pipeline ensures that high-level type specifications are progressively transformed into low-level token constraints that the generation process can enforce.\n\nSource: [llm.txt:1-15]()\n\n## The Term Classes\n\nThe `Term` class hierarchy forms the foundation of Outlines' regex DSL. All terms implement a common interface that supports composition operations and conversion to regex patterns.\n\nSource: [outlines/types/dsl.py:1-30]()\n\n### Core Term Classes\n\n| Term Class | Description | Standalone Usage |\n|------------|-------------|------------------|\n| `Regex` | Represents a raw regex pattern | Yes |\n| `String` | Literal string matching | Yes |\n| `JsonSchema` | JSON schema to regex conversion | Yes |\n| `CFG` | Context-free grammar constraints | Yes |\n| `Sequence` | Concatenation of multiple terms | No |\n| `Alternatives` | Choice between multiple terms | No |\n| `KleeneStar` | Zero or more repetitions | No |\n| `KleenePlus` | One or more repetitions | No |\n| `Optional` | Zero or one occurrence | No |\n\nSource: [outlines/types/dsl.py:30-80]()\n\n### Regex Class\n\nThe `Regex` class is a Pydantic-compatible type that represents a regular expression pattern. It can be used directly as a field type in Pydantic models.\n\n```python\nfrom outlines.types import Regex\nfrom pydantic import BaseModel\n\nage_type = Regex(\"[0-9]+\")\n\nclass User(BaseModel):\n name: str\n age: age_type\n```\n\nSource: [outlines/types/dsl.py:85-95]()\n\nThe `Regex` class provides the following composition operators:\n\n| Operator | Method | Description |\n|----------|--------|-------------|\n| `+` | `__add__` | Concatenate patterns (sequence) |\n| `\\|` | `__or__` | Create alternatives (choice) |\n| `r+` | `__radd__` | Right-side concatenation |\n| `r|` | `__ror__` | Right-side alternatives |\n\nSource: [outlines/types/dsl.py:97-115]()\n\n### JsonSchema Term\n\nThe `JsonSchema` term accepts a JSON schema string and converts it into regex constraints. This allows seamless integration with existing JSON schema definitions.\n\n```python\nfrom outlines import from_transformers\nfrom outlines.types import JsonSchema\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in JSON\", JsonSchema(json_schema))\n```\n\nSource: [outlines/release_note.md:1-25]()\n\n### CFG Term\n\nThe `CFG` (Context-Free Grammar) term allows definition of constraints using context-free grammar notation. This is useful for complex languages where regex alone is insufficient.\n\nSource: [outlines/types/dsl.py:75-80]()\n\n## Regex DSL Functions\n\nThe regex DSL provides utility functions for building complex patterns by combining simpler terms.\n\n### Composition Functions\n\n| Function | Description |\n|----------|-------------|\n| `either(*terms)` | Create alternatives from multiple terms |\n| `optional(term)` | Make a term optional (zero or one) |\n| `at_least(n, term)` | Require at least n occurrences |\n| `integer()` | Match integer patterns |\n| `float()` | Match floating-point number patterns |\n| `boolean()` | Match boolean patterns |\n\nSource: [outlines/release_note.md:1-30]()\n\n### Building Complex Patterns\n\nThe following example demonstrates building a complex regex pattern using the DSL:\n\n```python\nfrom outlines import from_transformers\nfrom outlines.types import at_least, either, integer, optional\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Build a pattern that matches email-like strings\npattern = either(\"user@example.com\", \"admin@company.org\")\n```\n\nSource: [outlines/release_note.md:25-35]()\n\n## Architecture\n\n### FSM Compilation Flow\n\n```mermaid\ngraph TD\n A[User Pattern Definition] --> B[Pydantic Model / Regex DSL]\n B --> C[JSON Schema Extraction]\n C --> D[Regex Generation]\n D --> E[FSM Compilation via interegular]\n E --> F[Token-Level Constraints]\n F --> G[Logits Masking during Generation]\n G --> H[Valid Output Generation]\n```\n\nSource: [llm.txt:15-25]()\n\n### Layer Stack\n\nThe regex system integrates with Outlines' layered architecture:\n\n```\nUser API (outlines.models)\n ↓\nGenerator Classes (SteerableGenerator, BlackBoxGenerator)\n ↓\nType System (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM Compilation (outlines-core: regex → FSM via interegular)\n ↓\nGuide System (processors/guide.py: FSM state management)\n ↓\nLogits Processing (processors/structured.py: token masking)\n ↓\nModel Providers (transformers, OpenAI, etc.)\n```\n\nSource: [llm.txt:30-45]()\n\n## Usage Patterns\n\n### Simple Classification with Literals\n\nWhile not strictly regex, Outlines uses the same constraint infrastructure for literal choices:\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\nSource: [outlines/release_note.md:60-75]()\n\n### Regex as Pydantic Field Types\n\nFor more complex validation, use `Regex` as a Pydantic field type:\n\n```python\nfrom outlines.types import Regex\nfrom pydantic import BaseModel\n\nclass ProductCode(BaseModel):\n code: Regex(r\"^[A-Z]{3}-[0-9]{4}$\")\n```\n\nThe `Regex` class implements Pydantic's schema generation and validation interfaces:\n\n| Method | Purpose |\n|--------|---------|\n| `__get_validator__` | Pydantic validator for input validation |\n| `__get_pydantic_core_schema__` | Core schema for Pydantic v2 integration |\n| `__get_pydantic_json_schema__` | JSON schema generation |\n\nSource: [outlines/types/dsl.py:117-130]()\n\n## Integration with Type System\n\n### Python Types to Terms Conversion\n\nThe `python_types_to_terms` function maps Python types to their corresponding Term representations:\n\n| Python Type | Term Equivalent |\n|-------------|------------------|\n| `int` | `integer()` |\n| `float` | `float()` |\n| `str` | `string` |\n| `bool` | `boolean()` |\n| `List[T]` | Pattern for lists |\n| `Literal[...]` | Alternatives |\n\nSource: [outlines/types/dsl.py:1-60]()\n\n### Schema Utilities\n\nThe type system includes utilities for converting between different schema formats:\n\n- `json_schema_dict_to_pydantic()`: Convert JSON schema to Pydantic model\n- `json_schema_dict_to_typeddict()`: Convert to TypedDict\n- `json_schema_dict_to_dataclass()`: Convert to dataclass\n\nSource: [outlines/types/dsl.py:50-55]()\n\n## Key Design Decisions\n\n### Token-Level Control\n\nOutlines' regex constraints operate at the token level, not character level. This means:\n\n1. FSMs are compiled from regex patterns using the `interegular` library\n2. State transitions map (state, token) → next_state\n3. For each state, invalid tokens are masked by setting their logits to negative infinity\n\nSource: [llm.txt:45-50]()\n\n### Lazy Compilation\n\nFSMs are compiled on first use and cached persistently. This ensures:\n- Initial overhead is minimal\n- Repeated generation with the same schema is fast\n- Memory is efficiently managed through caching\n\nSource: [llm.txt:50-55]()\n\n## API Reference\n\n### Regex Class\n\n```python\nclass Regex(Term):\n def __init__(self, pattern: str):\n \"\"\"Initialize with a regex pattern string.\"\"\"\n \n def __add__(self, other: Term) -> Sequence:\n \"\"\"Concatenate patterns.\"\"\"\n \n def __or__(self, other: Term) -> Alternatives:\n \"\"\"Create alternatives.\"\"\"\n \n def validate(self, value: Any) -> Any:\n \"\"\"Validate a value against the pattern.\"\"\"\n```\n\n### DSL Functions\n\n```python\ndef either(*terms: Term) -> Alternatives:\n \"\"\"Create alternatives from multiple terms.\"\"\"\n \ndef optional(term: Term) -> Term:\n \"\"\"Make a term optional (zero or one occurrence).\"\"\"\n \ndef at_least(n: int, term: Term) -> Term:\n \"\"\"Require at least n occurrences.\"\"\"\n \ndef integer() -> Term:\n \"\"\"Match integer patterns.\"\"\"\n \ndef boolean() -> Term:\n \"\"\"Match boolean patterns.\"\"\"\n```\n\nSource: [outlines/types/dsl.py:30-75]()\n\n## Best Practices\n\n1. **Pre-compile complex patterns**: If using the same pattern multiple times, consider using the `Generator` class to cache the FSM compilation\n\n2. **Use Pydantic models for complex structures**: JSON schema conversion provides a cleaner API for nested objects\n\n3. **Leverage composition operators**: Build complex patterns from simple terms using `+` and `|` operators\n\n4. **Test patterns separately**: Validate regex patterns independently before using them in generation\n\n## See Also\n\n- [Output Types Documentation](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/)\n- [Regex DSL Guide](https://dottxt-ai.github.io/outlines/latest/features/utility/regex_dsl/)\n- [Generator Documentation](https://dottxt-ai.github.io/outlines/latest/features/core/generator/)\n- [Context-Free Grammars](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/#context-free-grammars)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: dottxt-ai/outlines\n\nSummary: Found 30 potential pitfall items; 5 are high/blocking. Highest priority: installation - 来源证据：[Feature] Streaming structured generation with partial validation.\n\n## 1. installation · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. maintenance · 来源证据：Add more custom types\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. security_permissions · 来源证据：Add function calling and MCP support\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. security_permissions · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. installation · 失败模式：installation: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: Developers may fail before the first successful local run: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: OWASP ASI06 memory poisoning defense for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_aafbb33fe2e219639553f4d4275e0223 | https://github.com/dottxt-ai/outlines/issues/1864 | Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n## 7. installation · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- User impact: Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes\n\n## 8. installation · 失败模式：installation: Outlines v1.2.6\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.6\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 9. installation · 失败模式：installation: Outlines v1.2.8\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.8\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 10. installation · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 12. maintenance · 失败模式：migration: Outlines v1.2.10\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.10\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 13. maintenance · 失败模式：migration: Outlines v1.3.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.3.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 14. maintenance · 来源证据：Complex structure makes output empty\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 16. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 18. security_permissions · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. security_permissions · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. capability · 失败模式：capability: Add function calling and MCP support\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- User impact: Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 21. capability · 失败模式：capability: Add more custom types\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add more custom types\n- User impact: Developers may hit a documented source-backed failure mode: Add more custom types\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add more custom types. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 22. capability · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set. Context: Observed when using python, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_77f306218d1269b169d6fd1a5669ca47 | https://github.com/dottxt-ai/outlines/issues/1847 | TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n## 23. capability · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 24. capability · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 25. capability · 失败模式：conceptual: Complex structure makes output empty\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- User impact: Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 26. runtime · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add streaming support for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 27. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 28. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 29. maintenance · 失败模式：maintenance: Outlines v1.2.12\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.12\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 30. maintenance · 失败模式：maintenance: Outlines v1.2.9\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.9\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.9. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n\n\n",
"markdown_key": "outlines",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:615403340",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/dottxt-ai/outlines"
},
{
"evidence_id": "art_3090310aeb7a4bd8a2e8814423c876e1",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/dottxt-ai/outlines#readme"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "outlines 说明书",
"toc": [
"https://github.com/dottxt-ai/outlines Project Manual",
"Table of Contents",
"Introduction to Outlines",
"What Problem Does Outlines Solve?",
"Core Philosophy",
"Key Features",
"Architecture Overview",
"Getting Started",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "6ae21356fd0dda00afd0ef0e76752904a22fc0aa",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/index.md",
"docs/core_concepts.md",
"docs/blog/index.md",
"docs/community/index.md",
"docs/community/versioning.md",
"docs/community/contribute.md",
"docs/community/examples.md",
"docs/community/feedback.md",
"docs/guide/architecture.md",
"docs/guide/fastapi_vllm_deployment.md",
"docs/guide/getting_started.md",
"docs/guide/vlm.md",
"docs/guide/installation.md",
"docs/guide/chat_templating.md",
"docs/guide/core_concepts.md",
"docs/guide/migration.md",
"docs/guide/selecting_an_inference_backend.md",
"docs/examples/deploy-using-modal.md",
"docs/examples/models_playing_chess.md",
"docs/examples/deploy-using-cerebrium.md",
"docs/examples/index.md",
"docs/examples/chain_of_thought.md",
"docs/examples/extract_event_details.md",
"docs/examples/chain_of_density.md",
"docs/examples/deploy-using-bentoml.md",
"docs/examples/qa-with-citations.md",
"docs/examples/receipt-digitization.md",
"docs/examples/extraction.md",
"docs/examples/structured_generation_workflow.md",
"docs/examples/classification.md",
"docs/examples/knowledge_graph_extraction.md",
"docs/examples/react_agent.md",
"docs/examples/earnings-reports.md",
"docs/examples/extract_event_details.py",
"docs/examples/read-pdfs.md",
"docs/examples/dating_profiles.md",
"docs/examples/simtom.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# outlines - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 outlines 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install outlines` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：249\n- 重要文件覆盖：40/249\n- 证据索引条目：80\n- 角色 / Skill 条目：68\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 outlines 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 outlines 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 outlines 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 68 个角色 / Skill / 项目文档条目。\n\n- **Gemini**（project_doc）：You need to install the google.genai libray to be able to use the Gemini API in Outlines. Install all optional dependencies of the Gemini model with: pip install \"outlines gemini \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/gemini.md`\n- **🚀 Building the future of structured generation**（project_doc）：Made with ❤👷️ by the team at .txt https://dottxt.co Trusted by NVIDIA, Cohere, HuggingFace, vLLM, etc. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Deploy Outlines on Beam**（project_doc）：1. Create an account here https://beam.cloud and install the Beam SDK 2. Download the app.py file to your computer 3. Deploy it as a serverless API by running: beam deploy app.py:predict 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/beam-cloud/README.md`\n- **Core concepts**（project_doc）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/core_concepts.md`\n- **Index**（project_doc）：! assets/images/logo-light-mode.svg only-light { width=\"500\" } ! assets/images/logo-dark-mode.svg only-dark { width=\"500\" } 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **API Reference**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/index.md`\n- **Blog**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/index.md`\n- **What contributions?**（project_doc）：- Documentation contributions are very valuable to us! - Examples. Show us what you did with Outlines : - Bug reports with a minimum working examples in the issue tracker issues - Bug fixes are always a pleasure to review. - New features . Please start a new discussion discussions , or come chat with us discord beforehand! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/contribute.md`\n- **Community projects and articles**（project_doc）：Publishing examples and articles about Outlines are a meaningful way to contribute to the community. Here is a list of projects we are aware of. Drop us a line if we forgot yours! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/examples.md`\n- **Feedback**（project_doc）：If Outlines has been helpful to you, let us know on Discord discord or give us a shoutout on Twitter twitter ! It's always heartwarming ❤️ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/feedback.md`\n- **Community**（project_doc）：Outlines exists for a community of users who believe software doesn't need to be complicated. Who share the same passion for Large Language Models but don't want to compromise on robustness. Together, we are bringing these powerful models back to the world of software. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/index.md`\n- **Versioning Guide**（project_doc）：The Outlines project follows a structured versioning scheme designed to provide clarity and minimize risk for downstream dependents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/versioning.md`\n- **Summarize documents using Chain of Density prompting**（project_doc）：Summarize documents using Chain of Density prompting 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chain_of_density.md`\n- **Chain of thought**（project_doc）：Chain of thought is a prompting technique introduced in the paper \"Chain-of-Thought Prompting Elicits Reasoning in Large Language Models\" https://arxiv.org/abs/2201.11903 where throught prompting the authors generate a series of intermediate reasoning steps which improves the ability of LLMs to perform complex reasoning. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chain_of_thought.md`\n- **Classification**（project_doc）：Classification is a classic problem in NLP and finds many applications: spam detection, sentiment analysis, triaging of incoming requests, etc. We will use the example of a company that wants to sort support requests between those that require immediate attention URGENT , those that can wait a little STANDARD . You could easily extend the example by adding new labels. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/classification.md`\n- **Generate a synthetic dating profile from a description**（project_doc）：Generate a synthetic dating profile from a description 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/dating_profiles.md`\n- **Run Outlines using BentoML**（project_doc）：BentoML https://github.com/bentoml/BentoML is an open-source model serving library for building performant and scalable AI applications with Python. It comes with tools that you need for serving optimization, model packaging, and production deployment. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-bentoml.md`\n- **Run Outlines using Cerebrium**（project_doc）：Cerebrium https://www.cerebrium.ai/ is a serverless AI infrastructure platform that makes it easier for companies to build and deploy AI based applications. They offer Serverless GPU's with low cold start times with over 12 varieties of GPU chips that auto scale and you only pay for the compute you use. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-cerebrium.md`\n- **Run Outlines using Modal**（project_doc）：Modal https://modal.com/ is a serverless platform that allows you to easily run code on the cloud, including GPUs. It can come very handy for those of us who don't have a monster GPU at home and want to be able to quickly and easily provision, configure and orchestrate cloud infrastructure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/deploy-using-modal.md`\n- **Extracting financial data from earnings reports**（project_doc）：Extracting financial data from earnings reports 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/earnings-reports.md`\n- **Extract Event Details**（project_doc）：This recipe demonstrates how to use the outlines library to extract structured event details from a text message. We will extract the title, location, and start date and time from messages like the following: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/extract_event_details.md`\n- **Named entity extraction**（project_doc）：Named Entity Extraction is a fundamental problem in NLP. It involves identifying and categorizing named entities within a document: people, organization, dates, places, etc. It is usually the first step in a more complex NLP worklow. Here we will use the example of a pizza restaurant that receives orders via their website and need to identify the number and types of pizzas that are being ordered. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/extraction.md`\n- **Examples**（project_doc）：This part of the documentation provides a few cookbooks that you can browse to get acquainted with the library and get some inspiration about what you could do with structured generation. Remember that you can easily change the model that is being used! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/index.md`\n- **Knowledge Graph Extraction**（project_doc）：In this guide, we use outlines https://dottxt-ai.github.io/outlines/ to extract a knowledge graph from unstructured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/knowledge_graph_extraction.md`\n- **Large language models playing chess**（project_doc）：Large language models playing chess 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/models_playing_chess.md`\n- **Generate Synthetic Data and Q&A with Citations**（project_doc）：Generate Synthetic Data and Q&A with Citations 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/qa-with-citations.md`\n- **ReAct Agent**（project_doc）：This example shows how to use outlines https://dottxt-ai.github.io/outlines/ to build your own agent with open weights local models and structured outputs. It is inspired by the blog post A simple Python implementation of the ReAct pattern for LLMs https://til.simonwillison.net/llms/python-react-pattern by Simon Willison https://simonwillison.net/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/react_agent.md`\n- **PDF to structured output with vision language models**（project_doc）：PDF to structured output with vision language models 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/read-pdfs.md`\n- **Receipt Data Extraction with VLMs**（project_doc）：You'll need to install the dependencies: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/receipt-digitization.md`\n- **Build perspective-taking agents with SimToM**（project_doc）：Build perspective-taking agents with SimToM 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/simtom.md`\n- **Structured Generation Workflow: Generating Synthetic Phone Numbers**（project_doc）：Structured Generation Workflow: Generating Synthetic Phone Numbers 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/structured_generation_workflow.md`\n- **Structured Generation Backends**（project_doc）：Outlines relies on a structured generation backend to control text generation for steerable models such thah they conform to the output type provided. One of those backends is of course outlines-core , but you also have access to two other libraries that fulfill the same purpose: llguidance and xgrammar . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/advanced/backends.md`\n- **Logits Processors**（project_doc）：Logits processors are objects that control text generation by modifying the probability distribution of possible next tokens. They do this by adjusting the logits raw model outputs at each generation step, effectively biasing the model's token selection. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/advanced/logits_processors.md`\n- **Error Handling**（project_doc）：For server-based models, Outlines provides a common exception hierarchy under OutlinesError . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/exceptions.md`\n- **Generator**（project_doc）：The Generator class is the core component of Outlines v1. Generator accepts a model ../models/index.md and an optional output type ../core/output types.md . If no output type is provided, the Generator will return unstructured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/generator.md`\n- **Model Inputs**（project_doc）：Outlines models accept various types of inputs to generate text. The input format depends on the capabilities of the underlying model and the type of task you want to perform. The most basic type of input is a single string prompt, it's accepted by all models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/inputs.md`\n- **Output Types**（project_doc）：Outlines provides a simple and intuitive way of defining the output structure of text generation. Possible output formats include basic Python types, multiple-choices, JSON schemas, regular expressions and context-free grammars. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/core/output_types.md`\n- **Features**（project_doc）：This section presents in details the different features of Outlines. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/index.md`\n- **Anthropic**（project_doc）：You need to install the anthropic library to be able to use the Anthropic API in Outlines. Install all optional dependencies of the Anthropic model with: pip install \"outlines anthropic \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/anthropic.md`\n- **Dottxt**（project_doc）：You need to install the dottxt python sdk to be able to use the Dottxt API in Outlines. Install all optional dependencies of the Dottxt model with: pip install \"outlines dottxt \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/dottxt.md`\n- **Models**（project_doc）：Outlines models are objects that wrap an inference client or engine. Models provide a standardized interface to generate structured text. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/index.md`\n- **llama.cpp**（project_doc）：Outlines provides an integration with Llama.cpp https://github.com/ggerganov/llama.cpp using the llama-cpp-python library https://github.com/abetlen/llama-cpp-python . Llamacpp allows to run quantized models on machines with limited compute. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/llamacpp.md`\n- **Mistral**（project_doc）：You need to install the mistralai library to be able to use the Mistral API in Outlines. Install all optional dependencies of the Mistral model with: pip install \"outlines mistral \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/mistral.md`\n- **mlx-lm**（project_doc）：Outlines provides an integration with mlx-lm https://github.com/ml-explore/mlx-examples/tree/main/llms , allowing models to be run quickly on Apple Silicon via the mlx https://ml-explore.github.io/mlx/build/html/index.html library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/mlxlm.md`\n- **Ollama**（project_doc）：To be able to use Ollama in Outlines, you must install both Ollama and the optional dependency libraries of the model. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/ollama.md`\n- **OpenAI**（project_doc）：You need to install the openai library to be able to use the OpenAI API in Outlines. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openai.md`\n- **OpenAI-Compatible APIs**（project_doc）：Many inference providers offer OpenAI-compatible APIs, allowing you to use the familiar OpenAI SDK while connecting to different backends. Outlines allows you can leverage various providers while maintaining consistent code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openai_compatible.md`\n- **Openrouter**（project_doc）：OpenRouter https://openrouter.ai/docs/api-reference/overview uses the same API as OpenAI, so both services are interoperable ./openai compatible.md using the openai library. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/openrouter.md`\n- **SGLang**（project_doc）：The Outlines SGLang model is intended to be used along with an SGLang instance running on a separate server can be local or remote . Make sure you have a SGLang server running and accessible before using the SGLang model. For instance by running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/sglang.md`\n- **TGI**（project_doc）：The Outlines TGI model is intended to be used along with a HuggingFace Text Generation Inference server running locally or remotely . Make sure you have a TGI server running before using the TGI model. For instance running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/tgi.md`\n- **Transformers**（project_doc）：You need to install the transformers library to be able to use the Transformers in Outlines. Install all optional dependencies of the Transformers model with: pip install \"outlines transformers \" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/transformers.md`\n- **Transformers MultiModal**（project_doc）：The Outlines TransformersMultiModal model inherits from Transformers and shares most of its interface. Please start by reading the Transformers documentation ./transformers.md as this document only focuses on the specificities of TransformersMultiModal compared to Transformers . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/transformers_multimodal.md`\n- **vLLM**（project_doc）：The Outlines VLLM model is intended to be used along with a vLLM instance running on a separate server can be local or remote . Make sure you have a vLLM server running and accessible before using the VLLM model. For instance by running: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/vllm.md`\n- **vLLM Offline**（project_doc）：Outlines provides an integration with vLLM https://docs.vllm.ai/en/latest/ using the vllm library https://github.com/vllm-project/vllm . This model allows you to use vLLM in the \"Offline Inference\" mode, meaning that text generation happens within the model, there is no separate server. If you want to use vLLM with a server, see the VLLM model documentation ./vllm.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/models/vllm_offline.md`\n- **Application**（project_doc）：The Application class enables you to encapsulate a prompt template and an output type into a reusable component. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/application.md`\n- **Regex DSL**（project_doc）：This library provides a Domain-Specific Language DSL to construct regular expressions in a more intuitive and modular way. It allows you to create complex regexes using simple building blocks that represent literal strings, patterns, and various quantifiers. Additionally, these custom regex types can be used directly as types in Pydantic https://pydantic-docs.helpmanual.io/ schemas to enforce pattern constraints dur… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/regex_dsl.md`\n- **Template**（project_doc）：Outlines templates provide a way of creating reusable prompt structures with placeholders for dynamic content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/utility/template.md`\n- **Architecture Overview**（project_doc）：This guide explains how Outlines is organized so you can navigate the codebase, debug issues, and extend the library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/architecture.md`\n- **Chat templating**（project_doc）：Instruction-tuned language models use \"special tokens\" to indicate different parts of text, such as the system prompt, the user prompt, any images, and the assistant's response. A chat template https://huggingface.co/docs/transformers/main/en/chat templating is how different types of input are composited together into a single, machine-readable string. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/chat_templating.md`\n- **Core concepts**（project_doc）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/core_concepts.md`\n- **Deploying with FastAPI**（project_doc）：This guide demonstrates how to build a FastAPI application that leverages Outlines' async integration with vLLM. We create a customer support API that can intelligently categorize tickets and generate structured responses. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/fastapi_vllm_deployment.md`\n- **Getting Started**（project_doc）：We recommend using uv to install Outlines. You can find uv installation instructions here https://github.com/astral-sh/uv . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/getting_started.md`\n- **Installation**（project_doc）：We recommend using modern Python packaging tools such as uv for managing python dependencies. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/installation.md`\n- **Outlines 1.0 migration guide**（project_doc）：Outlines 1.0 introduces some breaking changes that affect the way you use the library. You are likely concerned by all of the following sections, so please read this document carefully until the end. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/migration.md`\n- **Models**（project_doc）：This guide should provide a general overview of the available models in the API reference /api/models/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/selecting_an_inference_backend.md`\n- **Vision-Language Models with Outlines**（project_doc）：Vision-Language Models with Outlines 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/vlm.md`\n- **Release Note**（project_doc）：The v1 intends on making Outlines more closely focused on constrained generation. To do so, we delegate a wider range of tasks to the users and inference libraries. On top of making Outlines leaner, this design provides more flexibility to the users and let them use interfaces they are already familiar with. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`outlines/release_note.md`\n- **🚧 Thank you for opening a PR!**（project_doc）：A few important guidelines and requirements before we can merge your PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Gemini**（documentation）：You need to install the google.genai libray to be able to use the Gemini API in Outlines. Install all optional dependencies of the Gemini model with: pip install \"outlines gemini \" . 证据：`docs/features/models/gemini.md`\n- **🚀 Building the future of structured generation**（documentation）：Made with ❤👷️ by the team at .txt https://dottxt.co Trusted by NVIDIA, Cohere, HuggingFace, vLLM, etc. 证据：`README.md`\n- **Deploy Outlines on Beam**（documentation）：1. Create an account here https://beam.cloud and install the Beam SDK 2. Download the app.py file to your computer 3. Deploy it as a serverless API by running: beam deploy app.py:predict 证据：`examples/beam-cloud/README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Core concepts**（documentation）：Coming soon. This will document various concepts at a high level, so users can understand Outlines before diving into specific implementations. 证据：`docs/core_concepts.md`\n- **Index**（documentation）：! assets/images/logo-light-mode.svg only-light { width=\"500\" } ! assets/images/logo-dark-mode.svg only-dark { width=\"500\" } 证据：`docs/index.md`\n- **API Reference**（documentation）：API Reference 证据：`docs/api_reference/index.md`\n- **Blog**（documentation）：Blog 证据：`docs/blog/index.md`\n- **What contributions?**（documentation）：- Documentation contributions are very valuable to us! - Examples. Show us what you did with Outlines : - Bug reports with a minimum working examples in the issue tracker issues - Bug fixes are always a pleasure to review. - New features . Please start a new discussion discussions , or come chat with us discord beforehand! 证据：`docs/community/contribute.md`\n- **Community projects and articles**（documentation）：Publishing examples and articles about Outlines are a meaningful way to contribute to the community. Here is a list of projects we are aware of. Drop us a line if we forgot yours! 证据：`docs/community/examples.md`\n- **Feedback**（documentation）：If Outlines has been helpful to you, let us know on Discord discord or give us a shoutout on Twitter twitter ! It's always heartwarming ❤️ 证据：`docs/community/feedback.md`\n- **Community**（documentation）：Outlines exists for a community of users who believe software doesn't need to be complicated. Who share the same passion for Large Language Models but don't want to compromise on robustness. Together, we are bringing these powerful models back to the world of software. 证据：`docs/community/index.md`\n- **Versioning Guide**（documentation）：The Outlines project follows a structured versioning scheme designed to provide clarity and minimize risk for downstream dependents. 证据：`docs/community/versioning.md`\n- **Summarize documents using Chain of Density prompting**（documentation）：Summarize documents using Chain of Density prompting 证据：`docs/examples/chain_of_density.md`\n- **Chain of thought**（documentation）：Chain of thought is a prompting technique introduced in the paper \"Chain-of-Thought Prompting Elicits Reasoning in Large Language Models\" https://arxiv.org/abs/2201.11903 where throught prompting the authors generate a series of intermediate reasoning steps which improves the ability of LLMs to perform complex reasoning. 证据：`docs/examples/chain_of_thought.md`\n- **Classification**（documentation）：Classification is a classic problem in NLP and finds many applications: spam detection, sentiment analysis, triaging of incoming requests, etc. We will use the example of a company that wants to sort support requests between those that require immediate attention URGENT , those that can wait a little STANDARD . You could easily extend the example by adding new labels. 证据：`docs/examples/classification.md`\n- **Generate a synthetic dating profile from a description**（documentation）：Generate a synthetic dating profile from a description 证据：`docs/examples/dating_profiles.md`\n- **Run Outlines using BentoML**（documentation）：BentoML https://github.com/bentoml/BentoML is an open-source model serving library for building performant and scalable AI applications with Python. It comes with tools that you need for serving optimization, model packaging, and production deployment. 证据：`docs/examples/deploy-using-bentoml.md`\n- **Run Outlines using Cerebrium**（documentation）：Cerebrium https://www.cerebrium.ai/ is a serverless AI infrastructure platform that makes it easier for companies to build and deploy AI based applications. They offer Serverless GPU's with low cold start times with over 12 varieties of GPU chips that auto scale and you only pay for the compute you use. 证据：`docs/examples/deploy-using-cerebrium.md`\n- **Run Outlines using Modal**（documentation）：Modal https://modal.com/ is a serverless platform that allows you to easily run code on the cloud, including GPUs. It can come very handy for those of us who don't have a monster GPU at home and want to be able to quickly and easily provision, configure and orchestrate cloud infrastructure. 证据：`docs/examples/deploy-using-modal.md`\n- **Extracting financial data from earnings reports**（documentation）：Extracting financial data from earnings reports 证据：`docs/examples/earnings-reports.md`\n- **Extract Event Details**（documentation）：This recipe demonstrates how to use the outlines library to extract structured event details from a text message. We will extract the title, location, and start date and time from messages like the following: 证据：`docs/examples/extract_event_details.md`\n- **Named entity extraction**（documentation）：Named Entity Extraction is a fundamental problem in NLP. It involves identifying and categorizing named entities within a document: people, organization, dates, places, etc. It is usually the first step in a more complex NLP worklow. Here we will use the example of a pizza restaurant that receives orders via their website and need to identify the number and types of pizzas that are being ordered. 证据：`docs/examples/extraction.md`\n- **Examples**（documentation）：This part of the documentation provides a few cookbooks that you can browse to get acquainted with the library and get some inspiration about what you could do with structured generation. Remember that you can easily change the model that is being used! 证据：`docs/examples/index.md`\n- **Knowledge Graph Extraction**（documentation）：In this guide, we use outlines https://dottxt-ai.github.io/outlines/ to extract a knowledge graph from unstructured text. 证据：`docs/examples/knowledge_graph_extraction.md`\n- **Large language models playing chess**（documentation）：Large language models playing chess 证据：`docs/examples/models_playing_chess.md`\n- **Generate Synthetic Data and Q&A with Citations**（documentation）：Generate Synthetic Data and Q&A with Citations 证据：`docs/examples/qa-with-citations.md`\n- **ReAct Agent**（documentation）：This example shows how to use outlines https://dottxt-ai.github.io/outlines/ to build your own agent with open weights local models and structured outputs. It is inspired by the blog post A simple Python implementation of the ReAct pattern for LLMs https://til.simonwillison.net/llms/python-react-pattern by Simon Willison https://simonwillison.net/ . 证据：`docs/examples/react_agent.md`\n- **PDF to structured output with vision language models**（documentation）：PDF to structured output with vision language models 证据：`docs/examples/read-pdfs.md`\n- **Receipt Data Extraction with VLMs**（documentation）：You'll need to install the dependencies: 证据：`docs/examples/receipt-digitization.md`\n- **Build perspective-taking agents with SimToM**（documentation）：Build perspective-taking agents with SimToM 证据：`docs/examples/simtom.md`\n- **Structured Generation Workflow: Generating Synthetic Phone Numbers**（documentation）：Structured Generation Workflow: Generating Synthetic Phone Numbers 证据：`docs/examples/structured_generation_workflow.md`\n- **Structured Generation Backends**（documentation）：Outlines relies on a structured generation backend to control text generation for steerable models such thah they conform to the output type provided. One of those backends is of course outlines-core , but you also have access to two other libraries that fulfill the same purpose: llguidance and xgrammar . 证据：`docs/features/advanced/backends.md`\n- **Logits Processors**（documentation）：Logits processors are objects that control text generation by modifying the probability distribution of possible next tokens. They do this by adjusting the logits raw model outputs at each generation step, effectively biasing the model's token selection. 证据：`docs/features/advanced/logits_processors.md`\n- **Error Handling**（documentation）：For server-based models, Outlines provides a common exception hierarchy under OutlinesError . 证据：`docs/features/core/exceptions.md`\n- **Generator**（documentation）：The Generator class is the core component of Outlines v1. Generator accepts a model ../models/index.md and an optional output type ../core/output types.md . If no output type is provided, the Generator will return unstructured text. 证据：`docs/features/core/generator.md`\n- **Model Inputs**（documentation）：Outlines models accept various types of inputs to generate text. The input format depends on the capabilities of the underlying model and the type of task you want to perform. The most basic type of input is a single string prompt, it's accepted by all models. 证据：`docs/features/core/inputs.md`\n- **Output Types**（documentation）：Outlines provides a simple and intuitive way of defining the output structure of text generation. Possible output formats include basic Python types, multiple-choices, JSON schemas, regular expressions and context-free grammars. 证据：`docs/features/core/output_types.md`\n- **Features**（documentation）：This section presents in details the different features of Outlines. 证据：`docs/features/index.md`\n- **Anthropic**（documentation）：You need to install the anthropic library to be able to use the Anthropic API in Outlines. Install all optional dependencies of the Anthropic model with: pip install \"outlines anthropic \" . 证据：`docs/features/models/anthropic.md`\n- **Dottxt**（documentation）：You need to install the dottxt python sdk to be able to use the Dottxt API in Outlines. Install all optional dependencies of the Dottxt model with: pip install \"outlines dottxt \" . 证据：`docs/features/models/dottxt.md`\n- **Models**（documentation）：Outlines models are objects that wrap an inference client or engine. Models provide a standardized interface to generate structured text. 证据：`docs/features/models/index.md`\n- **llama.cpp**（documentation）：Outlines provides an integration with Llama.cpp https://github.com/ggerganov/llama.cpp using the llama-cpp-python library https://github.com/abetlen/llama-cpp-python . Llamacpp allows to run quantized models on machines with limited compute. 证据：`docs/features/models/llamacpp.md`\n- **Mistral**（documentation）：You need to install the mistralai library to be able to use the Mistral API in Outlines. Install all optional dependencies of the Mistral model with: pip install \"outlines mistral \" . 证据：`docs/features/models/mistral.md`\n- **mlx-lm**（documentation）：Outlines provides an integration with mlx-lm https://github.com/ml-explore/mlx-examples/tree/main/llms , allowing models to be run quickly on Apple Silicon via the mlx https://ml-explore.github.io/mlx/build/html/index.html library. 证据：`docs/features/models/mlxlm.md`\n- **Ollama**（documentation）：To be able to use Ollama in Outlines, you must install both Ollama and the optional dependency libraries of the model. 证据：`docs/features/models/ollama.md`\n- **OpenAI**（documentation）：You need to install the openai library to be able to use the OpenAI API in Outlines. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 证据：`docs/features/models/openai.md`\n- **OpenAI-Compatible APIs**（documentation）：Many inference providers offer OpenAI-compatible APIs, allowing you to use the familiar OpenAI SDK while connecting to different backends. Outlines allows you can leverage various providers while maintaining consistent code. 证据：`docs/features/models/openai_compatible.md`\n- **Openrouter**（documentation）：OpenRouter https://openrouter.ai/docs/api-reference/overview uses the same API as OpenAI, so both services are interoperable ./openai compatible.md using the openai library. Install all optional dependencies of the OpenAI model with: pip install \"outlines openai \" . 证据：`docs/features/models/openrouter.md`\n- **SGLang**（documentation）：The Outlines SGLang model is intended to be used along with an SGLang instance running on a separate server can be local or remote . Make sure you have a SGLang server running and accessible before using the SGLang model. For instance by running: 证据：`docs/features/models/sglang.md`\n- **TGI**（documentation）：The Outlines TGI model is intended to be used along with a HuggingFace Text Generation Inference server running locally or remotely . Make sure you have a TGI server running before using the TGI model. For instance running: 证据：`docs/features/models/tgi.md`\n- **Transformers**（documentation）：You need to install the transformers library to be able to use the Transformers in Outlines. Install all optional dependencies of the Transformers model with: pip install \"outlines transformers \" . 证据：`docs/features/models/transformers.md`\n- **Transformers MultiModal**（documentation）：The Outlines TransformersMultiModal model inherits from Transformers and shares most of its interface. Please start by reading the Transformers documentation ./transformers.md as this document only focuses on the specificities of TransformersMultiModal compared to Transformers . 证据：`docs/features/models/transformers_multimodal.md`\n- **vLLM**（documentation）：The Outlines VLLM model is intended to be used along with a vLLM instance running on a separate server can be local or remote . Make sure you have a vLLM server running and accessible before using the VLLM model. For instance by running: 证据：`docs/features/models/vllm.md`\n- **vLLM Offline**（documentation）：Outlines provides an integration with vLLM https://docs.vllm.ai/en/latest/ using the vllm library https://github.com/vllm-project/vllm . This model allows you to use vLLM in the \"Offline Inference\" mode, meaning that text generation happens within the model, there is no separate server. If you want to use vLLM with a server, see the VLLM model documentation ./vllm.md . 证据：`docs/features/models/vllm_offline.md`\n- **Application**（documentation）：The Application class enables you to encapsulate a prompt template and an output type into a reusable component. 证据：`docs/features/utility/application.md`\n- **Regex DSL**（documentation）：This library provides a Domain-Specific Language DSL to construct regular expressions in a more intuitive and modular way. It allows you to create complex regexes using simple building blocks that represent literal strings, patterns, and various quantifiers. Additionally, these custom regex types can be used directly as types in Pydantic https://pydantic-docs.helpmanual.io/ schemas to enforce pattern constraints during text generation. 证据：`docs/features/utility/regex_dsl.md`\n- **Template**（documentation）：Outlines templates provide a way of creating reusable prompt structures with placeholders for dynamic content. 证据：`docs/features/utility/template.md`\n- **Architecture Overview**（documentation）：This guide explains how Outlines is organized so you can navigate the codebase, debug issues, and extend the library. 证据：`docs/guide/architecture.md`\n- **Chat templating**（documentation）：Instruction-tuned language models use \"special tokens\" to indicate different parts of text, such as the system prompt, the user prompt, any images, and the assistant's response. A chat template https://huggingface.co/docs/transformers/main/en/chat templating is how different types of input are composited together into a single, machine-readable string. 证据：`docs/guide/chat_templating.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/features/models/gemini.md`, `README.md`, `examples/beam-cloud/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/features/models/gemini.md`, `README.md`, `examples/beam-cloud/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Introduction to Outlines**：importance `high`\n - source_paths: README.md, outlines/__init__.py, outlines/release_note.md\n- **Quickstart Guide**：importance `high`\n - source_paths: README.md, docs/guide/getting_started.md\n- **Installation**：importance `high`\n - source_paths: docs/guide/installation.md, pyproject.toml, environment.yml\n- **Migration Guide**：importance `medium`\n - source_paths: docs/guide/migration.md, outlines/release_note.md\n- **System Architecture**：importance `high`\n - source_paths: docs/guide/architecture.md, outlines/generator.py, outlines/backends/__init__.py, llm.txt\n- **Core Concepts**：importance `high`\n - source_paths: docs/guide/core_concepts.md, docs/core_concepts.md, outlines/models/base.py\n- **Structured Generation Backends**：importance `high`\n - source_paths: outlines/backends/__init__.py, outlines/backends/base.py, outlines/backends/outlines_core.py, outlines/backends/xgrammar.py, outlines/backends/llguidance.py\n- **Output Types Overview**：importance `high`\n - source_paths: docs/features/core/output_types.md, outlines/types/__init__.py, outlines/types/dsl.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `6ae21356fd0dda00afd0ef0e76752904a22fc0aa`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/index.md`, `docs/core_concepts.md`, `docs/blog/index.md`, `docs/community/index.md`, `docs/community/versioning.md`, `docs/community/contribute.md`, `docs/community/examples.md`, `docs/community/feedback.md`, `docs/guide/architecture.md`, `docs/guide/fastapi_vllm_deployment.md`, `docs/guide/getting_started.md`, `docs/guide/vlm.md`, `docs/guide/installation.md`, `docs/guide/chat_templating.md`, `docs/guide/core_concepts.md`, `docs/guide/migration.md`, `docs/guide/selecting_an_inference_backend.md`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 来源证据：[Feature] Streaming structured generation with partial validation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 来源证据：Add more custom types\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 来源证据：Add function calling and MCP support\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 来源证据：[Feature Request] Add streaming support for structured generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 失败模式：installation: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Trigger: Developers should check this installation risk before relying on the project: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: OWASP ASI06 memory poisoning defense for structured generation. Context: Observed when using python\n- Why it matters: Developers may fail before the first successful local run: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Evidence: failure_mode_cluster:github_issue | fmev_aafbb33fe2e219639553f4d4275e0223 | https://github.com/dottxt-ai/outlines/issues/1864 | Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- Trigger: Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda\n- Why it matters: Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- Evidence: failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 失败模式：installation: Outlines v1.2.6\n\n- Trigger: Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- Why it matters: Upgrade or migration may change expected behavior: Outlines v1.2.6\n- Evidence: failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: 失败模式：installation: Outlines v1.2.8\n\n- Trigger: Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: Outlines v1.2.8\n- Evidence: failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 10: 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: dottxt-ai/outlines\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: local_cli\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 来源证据：[Feature] Streaming structured generation with partial validation (high): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation (high): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add more custom types (high): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add function calling and MCP support (high): 可能影响授权、密钥配置或安全边界。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Feature Request] Add streaming support for structured generation (high): 可能影响授权、密钥配置或安全边界。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/dottxt-ai/outlines Project Manual\n\nGenerated on: 2026-05-21 17:36:40 UTC\n\n## Table of Contents\n\n- [Introduction to Outlines](#page-introduction)\n- [Quickstart Guide](#page-quickstart)\n- [Installation](#page-installation)\n- [Migration Guide](#page-migration)\n- [System Architecture](#page-architecture)\n- [Core Concepts](#page-core-concepts)\n- [Structured Generation Backends](#page-backends)\n- [Output Types Overview](#page-output-types)\n- [JSON Schema and Pydantic Support](#page-json-schemas)\n- [Regex Patterns](#page-regex-patterns)\n\n\n\n## Introduction to Outlines\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture), [Quickstart Guide](#page-quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n \n\n# Introduction to Outlines\n\nOutlines is a Python library that enables **structured text generation** with Large Language Models (LLMs). It guarantees that model outputs conform to a specified structure during generation, eliminating the need for post-processing, regex parsing, or fragile code that breaks easily. Source: [README.md]()\n\n## What Problem Does Outlines Solve?\n\nLLMs are powerful but produce unpredictable outputs. Traditional approaches attempt to fix bad outputs after generation using parsing and regex, which is fragile and breaks easily. Outlines takes a different approach by ensuring structured outputs **during generation** rather than after. Source: [README.md]()\n\nThe core philosophy follows Python's own type system pattern: simply specify the desired output type, and Outlines ensures the generated data matches that structure exactly. Source: [README.md]()\n\n## Core Philosophy\n\nOutlines follows a simple pattern that mirrors Python's own type system:\n\n- For yes/no responses, use `Literal[\"Yes\", \"No\"]`\n- For numerical values, use `int`\n- For complex objects, define a structure with a [Pydantic model](https://docs.pydantic.dev/latest/)\n\nThis type-driven API makes structured generation feel natural to Python developers. Source: [README.md]()\n\n## Key Features\n\n### Universal Model Support\n\nOutlines works with any model provider with minimal code changes:\n\n| Model Type | Description | Documentation |\n|------------|-------------|---------------|\n| **Server Support** | vLLM and Ollama | Server Integrations |\n| **Local Model Support** | transformers and llama.cpp | Model Integrations |\n| **API Support** | OpenAI, Gemini, and Dottxt | API Integrations |\n\nSource: [README.md]()\n\n### Guaranteed Valid Structure\n\nOutlines provides several key guarantees:\n\n- **Works with any model** - Same code runs across OpenAI, Ollama, vLLM, and more\n- **Simple integration** - Just pass your desired output type: `model(prompt, output_type)`\n- **Guaranteed valid structure** - No more parsing headaches or broken JSON\n- **Provider independence** - Switch models without changing code\n\nSource: [README.md]()\n\n## Architecture Overview\n\n### Layer Stack\n\nOutlines follows a multi-layered architecture that transforms Python types into generation constraints:\n\n```\nUser API (outlines.models)\n ↓\nGenerator Classes (SteerableGenerator, BlackBoxGenerator)\n ↓\nType System (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM Compilation (outlines-core: regex → FSM via interegular)\n ↓\nGuide System (processors/guide.py: FSM state management)\n ↓\nLogits Processing (processors/structured.py: token masking)\n ↓\nModel Providers (transformers, OpenAI, etc.)\n```\n\nSource: [llm.txt]()\n\n### Key Design Decisions\n\n1. **FSM-based constraints**: For local models, constraints compile to finite state machines that track valid next tokens\n2. **Provider abstraction**: Same constraint system works across local models (transformers) and APIs (OpenAI)\n3. **Lazy compilation**: FSMs are compiled on first use and cached persistently\n4. **Token-level control**: Constraints apply at the token level, not character level\n5. **Type-driven API**: Python types are the primary interface for specifying constraints\n\nSource: [llm.txt]()\n\n### Model Class Hierarchy\n\nOutlines distinguishes between two types of model implementations:\n\n```mermaid\ngraph TD\n BaseModel[BaseModel]\n SteerableModel[SteerableModel - Controls logits]\n BlackBoxModel[BlackBoxModel - Uses provider's structured output]\n \n BaseModel --> SteerableModel\n BaseModel --> BlackBoxModel\n \n SteerableModel --> Transformers[Transformers]\n SteerableModel --> LlamaCpp[LlamaCpp]\n \n BlackBoxModel --> OpenAI[OpenAI]\n BlackBoxModel --> Gemini[Gemini]\n BlackBoxModel --> Anthropic[Anthropic]\n```\n\nSource: [llm.txt]()\n\n## Getting Started\n\n### Installation\n\nInstall Outlines using pip:\n\n```shell\npip install outlines\n```\n\nSource: [README.md]()\n\n### Basic Usage\n\n#### 1. Connect to a Model\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nSource: [README.md]()\n\n#### 2. Simple Structured Outputs\n\n```python\nfrom typing import Literal\nfrom pydantic import BaseModel\n\n\n# Simple classification\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n\n# Extract specific types\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\nSource: [README.md]()\n\n#### 3. Complex Structures with Pydantic\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n```\n\nSource: [README.md]()\n\n### Using Templates\n\nOutlines supports Jinja-based templates for dynamic prompt generation:\n\n```python\nimport outlines\nfrom typing import List, Literal\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n\nMODEL_NAME = \"microsoft/phi-4\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\n\n# Create a reusable template with Jinja syntax\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start>assistant\n\"\"\")\n\n# Generate prompts with different parameters\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# Use with structured generation\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\nSource: [README.md]()\n\n## Generator Pattern\n\nThe `Generator` class provides a reusable way to apply structured generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a generator with a specific output type\ngenerator = Generator(model, MyOutputType)\n\n# Reuse the generator multiple times\nresult1 = generator(\"Prompt 1\")\nresult2 = generator(\"Prompt 2\")\n```\n\nThe Generator class was introduced in v1 to address the need for reusable generation with a fixed output type, where output type compilation happens only once. Source: [outlines/release_note.md]()\n\n## Async Support\n\nOutlines provides comprehensive async support for both generation and streaming:\n\n### Async Model Methods\n\n```python\n# Direct model calling with async\nfrom pydantic import BaseModel\nfrom outlines import from_openai\nfrom openai import AsyncOpenAI\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_openai(AsyncOpenAI(), \"gpt-4o\")\nresult = await model(\"Create a character\", Character)\n```\n\nSource: [outlines/models/base.py]()\n\n### Async Streaming\n\n```python\nasync for chunk in model.stream(\"prompt\", OutputType):\n print(chunk)\n```\n\nSource: [outlines/models/base.py]()\n\n### Batch Processing\n\n```python\n# Batch generation\nresults = await model.batch([\"prompt1\", \"prompt2\"], OutputType)\n```\n\nSource: [outlines/models/base.py]()\n\n## API Model Integration\n\n### OpenAI\n\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import from_openai\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nSource: [outlines/release_note.md]()\n\n### Google Gemini\n\n```python\nfrom outlines import from_gemini\n\nmodel = from_gemini(client, \"gemini-pro\")\n```\n\nSource: [outlines/models/gemini.py]()\n\n## Exception Handling\n\nOutlines provides a comprehensive exception hierarchy for error handling:\n\n```\nOutlinesError\n├── APIError\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ ├── ServerError\n│ ├── APITimeoutError\n│ ├── APIConnectionError\n│ └── ProviderResponseError\n└── GenerationError\n```\n\nSource: [outlines/exceptions.py]()\n\nAll public exceptions inherit from `APIError` → `OutlinesError` → `Exception`. The `normalize_provider_exception` function converts raw provider SDK exceptions into the appropriate Outlines type. Source: [outlines/exceptions.py]()\n\n## Deployment Example\n\nOutlines can be deployed on various platforms. Here's an example using Modal:\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n\n\ndef import_model():\n from transformers import AutoModelForCausalLM, AutoTokenizer\n\n model_id = \"mistralai/Mistral-7B-Instruct-v0.2\"\n _ = AutoTokenizer.from_pretrained(model_id)\n _ = AutoModelForCausalLM.from_pretrained(model_id)\n\n\noutlines_image = outlines_image.run_function(import_model)\n```\n\nSource: [examples/modal_example.py]()\n\n## Migration from v0 to v1\n\nKey changes in the v1 API:\n\n| Feature | v0 | v1 |\n|---------|----|----|\n| Model initialization | `models.openai(\"gpt-4o\")` | `from_openai(OpenAI(), \"gpt-4o\")` |\n| Generation | `generate.json(model, Character)` | `Generator(model, Character)` |\n| Direct calling | N/A | `model(\"prompt\", OutputType)` |\n| Streaming | Separate method | `model.stream(\"prompt\", OutputType)` |\n\nSource: [outlines/release_note.md]()\n\n### Deprecated Features\n\n- `Exllamav2` model has been removed due to interface incompatibility\n- `function` module and `Function` class replaced by `Application`\n- `load_lora` methods on `VLLM` and `LlamaCpp` models deprecated in favor of direct initialization parameters\n- `TransformersVision` replaced by `TransformersMultiModal`\n\nSource: [outlines/release_note.md]()\n\n## See Also\n\n- [Model Integrations](../features/models/) - Detailed documentation for each model provider\n- [Generator](../features/core/generator/) - Generator class documentation\n- [Application](../features/utility/application/) - Application class for templated prompts\n- [Templates](../features/utility/template/) - Jinja-based template system\n\n---\n\n\n\n## Quickstart Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Outlines](#page-introduction), [Installation](#page-installation), [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n \n\n# Quickstart Guide\n\nThis guide provides a comprehensive introduction to Outlines, a structured text generation library for Large Language Models (LLMs). It covers installation, model setup, basic usage patterns, and common workflows to help you get started with guaranteed structured outputs from any LLM.\n\n## Overview\n\nOutlines ensures structured outputs during generation—directly from any LLM. Unlike post-processing approaches that parse and validate outputs after generation, Outlines enforces structure constraints at generation time. This eliminates parsing headaches, broken JSON, and fragile regex-based solutions.\n\n**Core capabilities:**\n\n- Works with any model (OpenAI, Ollama, vLLM, transformers, and more)\n- Simple integration using Python type annotations\n- Guaranteed valid structure output\n- Provider independence for easy model switching\n\nSource: [README.md:1-10]()\n\n## Installation\n\nInstall Outlines using pip:\n\n```shell\npip install outlines\n```\n\nSource: [README.md:31]()\n\n### Optional Dependencies\n\nDepending on your model provider, you may need additional packages:\n\n| Provider | Required Dependencies |\n|----------|----------------------|\n| transformers | `transformers`, `accelerate` |\n| OpenAI | `openai` |\n| Anthropic | `anthropic` |\n| Gemini | `google-genai` |\n| vLLM | `vllm` |\n| Ollama | `ollama` |\n\n## Connecting to Models\n\nOutlines provides factory functions to create model instances from various providers. The `from_transformers` function initializes a model using Hugging Face transformers.\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nSource: [README.md:37-46]()\n\n### Available Model Integrations\n\nOutlines supports multiple model providers through factory functions:\n\n| Model Type | Factory Function | Description |\n|------------|------------------|-------------|\n| Local (Transformers) | `from_transformers()` | Hugging Face transformers models |\n| OpenAI | `from_openai()` | OpenAI API models |\n| Anthropic | `from_anthropic()` | Anthropic Claude models |\n| Gemini | `from_gemini()` | Google Gemini models |\n| vLLM | `from_vllm()` | vLLM server deployment |\n| Ollama | `from_ollama()` | Ollama local server |\n| llama.cpp | `from_llamacpp()` | llama.cpp based models |\n\nSource: [llm.txt:1-20]()\n\n## Basic Structured Generation\n\n### Simple Classification\n\nUse `Literal` types for classification tasks with predefined categories:\n\n```python\nfrom typing import Literal\n\n# Simple classification\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\nSource: [README.md:55-62]()\n\n### Numerical Values\n\nGenerate structured numerical outputs by passing Python types:\n\n```python\n# Extract numerical values\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n```\n\nSource: [README.md:64-68]()\n\n### State Flow for Basic Generation\n\n```mermaid\ngraph TD\n A[User Prompt + Type] --> B[Outlines Model Call]\n B --> C{Output Type}\n C -->|Literal| D[Enum FSM Compilation]\n C -->|int/float| E[Number FSM Compilation]\n C -->|Pydantic| F[JSON Schema FSM Compilation]\n D --> G[Token Masking]\n E --> G\n F --> G\n G --> H[Constrained Generation]\n H --> I[Valid Structured Output]\n```\n\n## Complex Structures with Pydantic\n\nFor complex objects, define a structure using Pydantic models:\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\n# Generate structured review\nreview = model(\n \"Review a smartphone with great camera but poor battery life\",\n ProductReview\n)\n```\n\nSource: [README.md:70-88]()\n\n### Enum Types\n\nEnums constrain outputs to specific string values:\n\n```python\nfrom enum import Enum\n\nclass EventType(str, Enum):\n conference = \"conference\"\n webinar = \"webinar\"\n workshop = \"workshop\"\n meetup = \"meetup\"\n other = \"other\"\n\nclass EventInfo(BaseModel):\n name: str\n event_type: EventType\n topics: list[str]\n```\n\nSource: [README.md:1-50]()\n\n## Prompt Templates\n\nOutlines supports Jinja-based templates for dynamic prompt generation:\n\n```python\n# Create a reusable template with Jinja syntax\nsentiment_template = outlines.Template.from_string(\"\"\"\n<|im_start|>user\nAnalyze the sentiment of the following {{ content_type }}:\n\n{{ text }}\n\nProvide your analysis as either \"Positive\", \"Negative\", or \"Neutral\".\n<|im_end>\n<|im_start>assistant\n\"\"\")\n\n# Generate prompts with different parameters\nreview = \"This restaurant exceeded all my expectations. Fantastic service!\"\nprompt = sentiment_template(content_type=\"review\", text=review)\n\n# Use with structured generation\nresult = model(prompt, Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\nSource: [README.md:1-50]()\n\n### Loading Templates from Files\n\nTemplates can be loaded from external files for better organization:\n\n```python\n# Load template from file\nexample_template = outlines.Template.from_file(\"templates/few_shot.txt\")\n\n# Use with examples for few-shot learning\nexamples = [\n (\"The food was cold\", \"Negative\"),\n (\"The staff was friendly\", \"Positive\")\n]\nfew_shot_prompt = example_template(examples=examples, query=\"Service was slow\")\n```\n\nSource: [README.md:1-50]()\n\n## Handling Incomplete Data with Union Types\n\nUse Union types to handle cases where data might be incomplete:\n\n```python\nfrom typing import Union\n\n# Create a union type that can either be a structured response or fallback\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\n# Parse event details - returns EventInfo or \"I don't know\"\nresult = model(\n \"Join us for DevCon 2024 in San Francisco on March 15th\",\n EventResponse\n)\n```\n\nSource: [README.md:1-50]()\n\n## Using the Generator Class\n\nThe `Generator` class encapsulates a model with a specific output type, allowing reusable structured generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom typing import Literal\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a reusable generator\nchoice_generator = Generator(model, Literal[\"pizza\", \"burger\", \"tacos\"])\n\n# Use the generator multiple times\nresult1 = choice_generator(\"What should I eat for lunch?\")\nresult2 = choice_generator(\"Dinner options?\")\n```\n\nSource: [outlines/release_note.md:1-50]()\n\n### Generator vs Direct Model Calling\n\n| Aspect | Direct Model Call | Generator |\n|--------|-------------------|-----------|\n| Output type | Specified per call | Fixed at initialization |\n| Compilation | Occurs each call | Occurs once |\n| Reusability | Single use | Multiple uses |\n| Best for | Varying output types | Consistent output types |\n\nSource: [outlines/release_note.md:1-50]()\n\n## Function Calling with Applications\n\nThe `Application` class provides a way to define functions with typed parameters that LLMs can call:\n\n```python\nfrom outlines import Application, Template, from_transformers\nfrom pydantic import BaseModel\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom typing import List, Optional\nfrom datetime import date\n\n# Define a function with typed parameters\ndef schedule_meeting(\n title: str,\n date: date,\n duration_minutes: int,\n attendees: List[str],\n location: Optional[str] = None,\n agenda_items: Optional[List[str]] = None\n):\n \"\"\"Schedule a meeting with the specified details\"\"\"\n meeting = {\n \"title\": title,\n \"date\": date,\n \"duration_minutes\": duration_minutes,\n \"attendees\": attendees,\n \"location\": location,\n \"agenda_items\": agenda_items\n }\n return f\"Meeting '{title}' scheduled for {date}\"\n\n# Create model and template\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/phi-4\"),\n AutoTokenizer.from_pretrained(\"microsoft/phi-4\")\n)\n\ntemplate = Template.from_string(\"\"\"\nExtract meeting details from: {{ request }}\n\"\"\")\n\n# Create application\napp = Application(template, schedule_meeting)\n\n# Natural language request\nuser_request = \"\"\"\nI need to set up a team sync next Monday at 2pm for 30 minutes.\nInclude John and Sarah. We'll discuss the Q1 roadmap.\n\"\"\"\n\n# Execute\nresult = app(model, {\"request\": user_request})\n```\n\nSource: [README.md:1-50]()\n\n### Application Pattern Workflow\n\n```mermaid\ngraph TD\n A[Natural Language Request] --> B[Application]\n B --> C[Template Variables]\n C --> D[Structured Prompt]\n D --> E[LLM Generation]\n E --> F[Function Schema]\n F --> G[Parameter Extraction]\n G --> H[Typed Function Call]\n H --> I[Structured Result]\n```\n\n## Generation Parameters\n\nPass additional inference arguments to model calls:\n\n```python\n# Beam search for better quality\nresult = model(\n \"Write a short story about a cat\",\n str,\n num_beams=2\n)\n\n# Streaming responses\nfor chunk in model.stream(\"Tell me a joke\", str):\n print(chunk, end=\"\", flush=True)\n```\n\nSource: [outlines/release_note.md:1-50]()\n\n## Deployment Examples\n\n### Modal Deployment\n\nOutlines can be deployed on Modal for serverless inference:\n\n```python\nimport modal\n\napp = modal.App(name=\"outlines-app\")\n\noutlines_image = modal.Image.debian_slim(python_version=\"3.11\").pip_install(\n \"outlines==1.0.0\",\n \"transformers==4.38.2\",\n \"datasets==2.18.0\",\n \"accelerate==0.27.2\",\n)\n\ndef import_model():\n from transformers import AutoModelForCausalLM, AutoTokenizer\n model_id = \"mistralai/Mistral-7B-Instruct-v0.2\"\n _ = AutoTokenizer.from_pretrained(model_id)\n _ = AutoModelForCausalLM.from_pretrained(model_id)\n\noutlines_image = outlines_image.run_function(import_model)\n```\n\nSource: [examples/modal_example.py:1-30]()\n\n## Next Steps\n\n| Topic | Description |\n|-------|-------------|\n| [Installation Guide](guide/installation.md) | Detailed installation instructions for all providers |\n| [Model Integrations](features/models/index.md) | Complete reference for all supported models |\n| [Output Types](features/core/output_types.md) | Deep dive into type system and constraints |\n| [Templates](features/utility/template.md) | Advanced template usage and patterns |\n| [Applications](features/utility/application.md) | Building reusable structured applications |\n| [Architecture](guide/architecture.md) | Understanding the internal design |\n\n## Quick Reference\n\n```python\n# Complete minimal example\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\nfrom pydantic import BaseModel\n\n# 1. Load model\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# 2. Define output structure\nclass Answer(BaseModel):\n response: str\n confidence: float\n\n# 3. Generate with structure guarantee\nresult = model(\"What is the capital of France?\", Answer)\n```\n\nThis quickstart covers the essential patterns for using Outlines. The library's type-driven approach ensures that outputs always match your specified structure, eliminating the need for fragile post-processing.\n\n---\n\n\n\n## Installation\n\n### Related Pages\n\nRelated topics: [Quickstart Guide](#page-quickstart), [Structured Generation Backends](#page-backends)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottext-ai/outlines/blob/main/README.md)\n- [release_note.md](https://github.com/dottxt-ai/outlines/blob/main/release_note.md)\n- [examples/modal_example.py](https://github.com/dottxt-ai/outlines/blob/main/examples/modal_example.py)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n \n\n# Installation\n\nThis guide covers all methods for installing Outlines, a structured text generation library for Large Language Models.\n\n## Overview\n\nOutlines provides structured output generation for LLMs by ensuring outputs match specified types during generation. The installation process is straightforward via pip, with optional dependencies for specific model backends. Source: [README.md:1-10]()\n\n## Prerequisites\n\n### Python Version\n\nOutlines requires Python 3.10 or later. Ensure your environment has an appropriate Python installation before proceeding.\n\n### Core Dependencies\n\nThe following table lists the core dependencies required by Outlines:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `interegular` | Latest | FSM compilation for regex-based constraints |\n| `jinja2` | Latest | Template processing |\n| `pydantic` | 2.x | Data validation and structure definitions |\n\n## Installation Methods\n\n### Standard Installation (pip)\n\nThe simplest way to install Outlines is via pip:\n\n```bash\npip install outlines\n```\n\nSource: [README.md:15-18]()\n\n### Development Installation\n\nFor contributors or those wanting the latest unreleased features, install from source:\n\n```bash\ngit clone https://github.com/dottxt-ai/outlines.git\ncd outlines\npip install -e \".[dev]\"\n```\n\n## Optional Dependencies by Model Backend\n\nOutlines supports multiple model providers. Install backend-specific dependencies based on your use case.\n\n### Hugging Face Transformers\n\nFor local model inference using Hugging Face Transformers:\n\n```bash\npip install outlines[transformers]\n```\n\nRequired packages:\n\n| Package | Purpose |\n|---------|---------|\n| `transformers` | Model loading and inference |\n| `accelerate` | GPU acceleration support |\n| `datasets` | Dataset utilities |\n| `torch` | Deep learning framework |\n\nSource: [examples/modal_example.py:5-9]()\n\n```python\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\n### OpenAI Models\n\nFor OpenAI API integration:\n\n```bash\npip install outlines[openai]\n```\n\nRequired packages:\n\n| Package | Purpose |\n|---------|---------|\n| `openai` | Official OpenAI Python client |\n\nSource: [README.md:20-35]()\n\n```python\nfrom openai import OpenAI\nfrom outlines import from_openai\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\n### Anthropic Models\n\nFor Anthropic Claude integration:\n\n```bash\npip install outlines[anthropic]\n```\n\n### Google Gemini Models\n\n```bash\npip install outlines[gemini]\n```\n\nSource: [outlines/models/gemini.py:80-95]()\n\n### Local Model Backends\n\nFor running models locally via vLLM, llama.cpp, or SGLang:\n\n```bash\npip install outlines[vllm] # For vLLM backend\npip install outlines[sglang] # For SGLang backend\n```\n\nSource: [llm.txt:30-50]()\n\n### Async Support\n\nFor asynchronous inference with async model backends:\n\n```bash\npip install outlines[async]\n```\n\nThe async backends available are:\n\n| Backend | Class | Purpose |\n|---------|-------|---------|\n| AsyncSGLang | `AsyncSGLang` | Async SGLang inference |\n| AsyncTGI | `AsyncTGI` | Async Text Generation Inference |\n| AsyncVLLM | `AsyncVLLM` | Async vLLM inference |\n\nSource: [release_note.md:45-60]()\n\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\n## Quick Start After Installation\n\nOnce installed, you can begin using Outlines immediately:\n\n```python\nimport outlines\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\n\n# Load a model\nMODEL_NAME = \"microsoft/Phi-3-mini-4k-instruct\"\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(MODEL_NAME, device_map=\"auto\"),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n\n# Generate structured output\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\n```\n\nSource: [README.md:40-60]()\n\n## GPU Setup\n\nFor optimal performance with local models, configure GPU acceleration:\n\n```python\n# Device mapping for multi-GPU setups\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\n MODEL_NAME, \n device_map=\"auto\"\n ),\n AutoTokenizer.from_pretrained(MODEL_NAME)\n)\n```\n\nThe `device_map=\"auto\"` parameter enables automatic GPU allocation across available devices.\n\n## Verifying Installation\n\nVerify your installation by running:\n\n```python\nimport outlines\nprint(outlines.__version__) # Check installed version\n```\n\n## Common Installation Issues\n\n### Missing Dependencies\n\nIf you encounter import errors, ensure all required dependencies are installed for your specific use case. Reinstall with the appropriate extras:\n\n```bash\npip install --upgrade outlines[]\n```\n\n### CUDA/GPU Compatibility\n\nFor CUDA support with transformers, ensure `accelerate` is installed:\n\n```bash\npip install accelerate\n```\n\n### Version Conflicts\n\nIf upgrading from v0.x to v1.x, note the following breaking changes:\n\n| v0.x | v1.x |\n|------|------|\n| `models.openai(\"gpt-4o\")` | `from_openai(OpenAI(), \"gpt-4o\")` |\n| `generate.json(model, schema)` | `model(prompt, schema)` |\n| `Function` class | `Application` class |\n\nSource: [release_note.md:100-130]()\n\n## Next Steps\n\nAfter installation, explore these topics:\n\n- [Quick Start Guide](getting-started.md) - Generate your first structured output\n- [Model Integrations](../features/models.md) - Configure different model backends\n- [Structured Generation](../features/structured-outputs.md) - Learn about type-constrained generation\n\n---\n\n\n\n## Migration Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Outlines](#page-introduction), [Quickstart Guide](#page-quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [docs/guide/migration.md](https://github.com/dottxt-ai/outlines/blob/main/docs/guide/migration.md)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n \n\n# Migration Guide\n\nThis guide provides comprehensive documentation for migrating from Outlines v0 to v1. The v1 release introduces significant API changes that improve consistency, usability, and maintainability while preserving the core functionality of structured text generation with LLMs.\n\n## Overview\n\nOutlines v1 represents a major evolution of the library's architecture, focusing on:\n\n- **Unified Model Interface**: All model providers now share a consistent calling pattern\n- **Simplified Output Type Handling**: The `Generator` class replaces multiple specialized generate functions\n- **Type-driven API**: Python types remain the primary interface for specifying constraints\n- **Enhanced Streaming**: All models now support streaming as a first-class feature\n\nSource: [outlines/release_note.md:1-50]()\n\n## High-Level Architecture Changes\n\nThe following diagram illustrates the architectural changes between v0 and v1:\n\n```mermaid\ngraph TD\n subgraph v0_Architecture\n A0[User Code] --> B0[models]\n B0 --> C0[generate.json/choice/...]\n C0 --> D0[Generator with fixed output type]\n end\n \n subgraph v1_Architecture\n A1[User Code] --> B1[from_transformers/from_openai/...]\n B1 --> C1[Model Instance]\n A1 --> D1[Generator Model, OutputType]\n D1 --> E1[Reusable Generator]\n end\n \n style v0_Architecture fill:#ffcccc\n style v1_Architecture fill:#ccffcc\n```\n\n## Migration by Component\n\n### Model Initialization\n\n#### Transformers Models\n\n| Aspect | v0 | v1 |\n|--------|-----|-----|\n| Entry point | `models.transformers()` | `outlines.from_transformers()` |\n| Model loading | Inline with Outlines initialization | Separately via HuggingFace |\n| Tokenizer | Passed to Outlines | Explicitly loaded and passed |\n| Configuration | Scattered across `model_kwargs` | Standard HuggingFace initialization |\n\n**v0 (Deprecated):**\n```python\nfrom outlines import models\nfrom transformers import BertForSequenceClassification, BertTokenizer\n\nmodel = models.transformers(\n model_name=\"prajjwal1/bert-tiny\",\n model_class=BertForSequenceClassification,\n tokenizer_class=BertTokenizer,\n model_kwargs={\"use_cache\": False},\n tokenizer_kwargs={\"model_max_length\": 512},\n)\n```\n\n**v1 (Current):**\n```python\nimport outlines\nfrom transformers import BertForSequenceClassification, BertTokenizer\n\nhf_model = BertForSequenceClassification.from_pretrained(\n \"prajjwal1/bert-tiny\", \n use_cache=False\n)\nhf_tokenizer = BertTokenizer.from_pretrained(\n \"prajjwal1/bert-tiny\", \n model_max_length=512\n)\nmodel = outlines.from_transformers(hf_model, hf_tokenizer)\n```\n\nSource: [outlines/release_note.md:45-60]()\n\n#### OpenAI Models\n\n| Aspect | v0 | v1 |\n|--------|-----|-----|\n| Init signature | `OpenAI(client, OpenAIConfig())` | `OpenAI(client, model_name)` |\n| Inference args | In `OpenAIConfig` | In model call |\n| Recommendation | Direct initialization | Use `from_openai()` |\n\n**v0 (Deprecated):**\n```python\nfrom outlines import models\n\nmodel = models.openai(\"gpt-4o\", config)\nresult = generator(\"Create a character\")\n```\n\n**v1 (Current):**\n```python\nfrom openai import OpenAI\nfrom outlines import from_openai\n\nclient = OpenAI()\nmodel = from_openai(client, \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nSource: [outlines/release_note.md:65-80]()\n\n### Generation API Changes\n\n#### Generator Class Introduction\n\nThe `Generator` class provides a reusable interface where the output type is compiled only once:\n\n```mermaid\nclassDiagram\n class Generator {\n +model: Model\n +output_type: OutputType\n +__init__(model, output_type)\n +__call__(prompt, **kwargs) Any\n +stream(prompt, **kwargs) Iterator\n }\n \n class Model {\n <>\n +__call__(prompt, output_type, **kwargs) Any\n +stream(prompt, output_type, **kwargs) Iterator\n }\n \n class OutputType {\n <>\n }\n \n Generator --> Model : uses\n Generator --> OutputType : compiles\n```\n\n**Usage Pattern:**\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Create a reusable generator\ngenerator = Generator(model, Character)\n\n# Use multiple times without recompiling the output type\nresult1 = generator(\"Create a hero character\")\nresult2 = generator(\"Create a villain character\")\n```\n\nSource: [outlines/release_note.md:25-45]()\n\n#### Direct Model Calling\n\nAll models can now be called directly with a prompt and output type:\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Direct calling with output type\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n\n# Streaming support\nfor chunk in model.stream(\"Tell me a story\", str):\n print(chunk, end=\"\", flush=True)\n```\n\nSource: [outlines/release_note.md:18-25]()\n\n### Function to Application Migration\n\nThe `Function` class has been deprecated in favor of the `Application` class:\n\n| Aspect | v0 (`Function`) | v1 (`Application`) |\n|--------|-----------------|-------------------|\n| Model binding | At initialization | At call time |\n| Template variables | As `**kwargs` | As dictionary |\n| Reusability | Single model/output type | Multiple models supported |\n\n**v0 (Deprecated):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import Function, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\nfn = Function(template, Character, \"hf-internal-testing/tiny-random-GPTJForCausalLM\")\nresponse = fn(gender=\"female\")\n```\n\n**v1 (Current):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import Application, Template, from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\nresponse = app(model, {\"gender\": \"female\"})\n```\n\nSource: [outlines/release_note.md:80-95]()\n\n### Generate Module Deprecation\n\nThe `generate` module and its specialized functions have been consolidated:\n\n| v0 Function | v1 Equivalent |\n|-------------|---------------|\n| `generate.json()` | `Generator(model, PydanticModel)` |\n| `generate.choice()` | `Generator(model, Literal[\"A\", \"B\"])` |\n| `generate.regex()` | `Generator(model, str) with FSM constraint` |\n\n**v0 (Deprecated):**\n```python\nfrom pydantic import BaseModel\nfrom outlines import generate, models\n\nclass Character(BaseModel):\n name: str\n\nmodel = models.openai(\"gpt-4o\")\ngenerator = generate.json(model, Character)\nresult = generator(\"Create a character\")\n```\n\n**v1 (Current):**\n```python\nfrom openai import OpenAI\nfrom pydantic import BaseModel\nfrom outlines import Generator, from_openai\n\nclass Character(BaseModel):\n name: str\n\nclient = OpenAI()\nmodel = from_openai(client, \"gpt-4o\")\ngenerator = Generator(model, Character)\nresult = generator(\"Create a character\")\n```\n\nSource: [outlines/release_note.md:95-110]()\n\n## Async Model Support\n\nv1 introduces new async model providers for asynchronous inference:\n\n| Model | Factory Function | Description |\n|-------|-----------------|-------------|\n| `AsyncSGLang` | `from_sglang()` | SGLang async backend |\n| `AsyncTGI` | `from_tgi()` | Text Generation Inference |\n| `AsyncVLLM` | `from_vllm()` | vLLM async backend |\n\n**Usage:**\n```python\nimport outlines\nfrom huggingface_hub import AsyncInferenceClient\n\nasync_model = outlines.from_tgi(AsyncInferenceClient(\"http://localhost:11434\"))\n```\n\nSource: [outlines/release_note.md:10-18]()\n\n## Deprecated Features\n\n### Exllamav2 Model\n\nThe `Exllamav2` model has been deprecated without replacement:\n\n- **Reason**: Interface incompatibility with Outlines' constraint system\n- **Impact**: Required cumbersome runtime patching\n- **Action**: Migrate to supported local inference backends (transformers, llama.cpp, vLLM)\n\n## Quick Reference\n\n### Import Changes\n\n| Old Import | New Import |\n|------------|------------|\n| `from outlines import models` | `from outlines import from_transformers, from_openai, ...` |\n| `from outlines import generate` | `from outlines import Generator` |\n| `from outlines import Function` | `from outlines import Application` |\n\n### Common Migration Patterns\n\n```python\n# JSON output - v0 to v1\n# v0: generate.json(model, MySchema)\n# v1: Generator(model, MySchema)\n\n# Choice selection - v0 to v1\n# v0: generate.choice(model, [\"option1\", \"option2\"])\n# v1: model(prompt, Literal[\"option1\", \"option2\"])\n\n# Streaming - v0 to v1\n# v0: generator = generate.json(model, Schema); result = generator.stream(prompt)\n# v1: for chunk in model.stream(prompt, Schema): process(chunk)\n```\n\n## Documentation References\n\nFor additional information, consult the following resources:\n\n- [Models Overview](https://dottxt-ai.github.io/outlines/latest/features/models)\n- [Generator Guide](https://dottxt-ai.github.io/outlines/latest/features/core/generator)\n- [Application Guide](https://dottxt-ai.github.io/outlines/latest/features/utility/application)\n- [Python Types Guide](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/#basic-python-types)\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Structured Generation Backends](#page-backends), [Core Concepts](#page-core-concepts)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [llm.txt](https://github.com/dottext-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [docs/guide/architecture.md](https://github.com/dottxt-ai/outlines/blob/main/docs/guide/architecture.md)\n \n\n# System Architecture\n\n## Overview\n\nOutlines is a structured text generation library for Large Language Models (LLMs). Its core architectural purpose is to guarantee that LLM outputs conform to developer-specified schemas and constraints during generation, rather than attempting to parse and fix invalid outputs after generation.\n\nThe architecture achieves this through a multi-layered system that compiles output type specifications into finite state machines (FSMs), which are then used to constrain token selection at the logits processing level. This approach provides provider independence, allowing the same constraint system to work across both local models (where logits can be directly controlled) and API-based models (where structured output APIs are leveraged when available).\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Layer Stack Architecture\n\nOutlines follows a strict layered architecture where each layer has a specific responsibility and communicates with adjacent layers through well-defined interfaces.\n\n```mermaid\ngraph TD\n A[\"User API
(outlines.models)\"] --> B[\"Generator Classes
(SteerableGenerator, BlackBoxGenerator)\"]\n B --> C[\"Type System
(types/dsl.py)\"]\n C --> D[\"FSM Compilation
(outlines-core: regex → FSM)\"]\n D --> E[\"Guide System
(processors/guide.py)\"]\n E --> F[\"Logits Processing
(processors/structured.py)\"]\n F --> G[\"Model Providers
(transformers, OpenAI, etc.)\"]\n \n style A fill:#e1f5ff\n style G fill:#fff3e1\n style C fill:#e8f5e9\n style D fill:#f3e5f5\n```\n\n### Layer Descriptions\n\n| Layer | File Location | Purpose |\n|-------|---------------|---------|\n| User API | `outlines/models/` | Entry point for model initialization and generation calls |\n| Generator Classes | `outlines/generator.py` | Manages reusable generation with cached FSM compilation |\n| Type System | `outlines/types/dsl.py` | Converts Python types and Pydantic models to JSON Schema and Regex |\n| FSM Compilation | `outlines-core` | Transforms regex patterns into finite state machines via interegular |\n| Guide System | `processors/guide.py` | Manages FSM state transitions during token generation |\n| Logits Processing | `processors/structured.py` | Masks invalid tokens by modifying logits before sampling |\n| Model Providers | `outlines/models/*.py` | Provider-specific adapters for different LLM backends |\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Core Components\n\n### Model Classes\n\nThe model layer defines two fundamental abstract base classes that reflect the fundamental difference in how Outlines interacts with different types of LLM backends.\n\n#### SteerableModel\n\n`SteerableModel` is the base class for models where Outlines has direct control over the sampling process. This includes:\n\n- Local models via the `Transformers` backend\n- llama.cpp-based models via the `Llamacpp` backend\n- MLX-accelerated models via the `MlxLm` backend\n\nFor steerable models, Outlines can apply logits processors that mask invalid tokens based on the compiled FSM, ensuring constraint satisfaction at generation time.\n\nSource: [outlines/models/base.py:1-50](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n#### BlackBoxModel\n\n`BlackBoxModel` is the base class for API-based models where the model provider controls the generation process. This includes:\n\n- OpenAI models\n- Anthropic models\n- Google Gemini models\n- Ollama (when used as an API)\n\nFor black box models, Outlines leverages provider-specific structured output APIs when available, or falls back to prompting strategies. The constraint system cannot directly mask tokens, so the approach adapts based on provider capabilities.\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Generator System\n\nThe `Generator` class provides a reusable abstraction for generation that encapsulates both the model and output type specification.\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n age: int\n\nmodel = from_transformers(...)\ngenerator = Generator(model, Character)\n\n# FSM compilation happens once\nresult = generator(\"Create a character\")\n```\n\nKey benefits of the Generator abstraction:\n\n1. **Lazy Compilation**: FSMs are compiled on first use and cached persistently\n2. **Reusability**: The same generator can be called multiple times without re-specifying the output type\n3. **Separation of Concerns**: Model configuration and output type specification are decoupled\n\nSource: [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n### Async Model Support\n\nAll model classes inherit from `AsyncModelMixin`, providing consistent async interfaces across all providers:\n\n```python\nasync def __call__(self, model_input, output_type=None, backend=None, **inference_kwargs)\nasync def batch(self, model_inputs, output_type=None, backend=None, **inference_kwargs)\nasync def stream(self, model_input, output_type=None, backend=None, **inference_kwargs)\n```\n\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Provider Abstraction\n\nThe architecture uses a factory pattern with provider-specific adapter classes that handle input and output format conversion.\n\n```mermaid\ngraph LR\n A[User Code] --> B[\"from_transformers() / from_openai() / etc.\"]\n B --> C[\"Model Instance
(Transformers / OpenAI / etc.)\"]\n C --> D[\"Provider Adapter\"]\n D --> E[\"Generation Method\"]\n \n style B fill:#e8f5e9\n```\n\n### Supported Providers\n\n| Provider | Factory Function | Model Class | Control Type |\n|----------|-----------------|-------------|--------------|\n| Hugging Face Transformers | `from_transformers()` | `Transformers` | Steerable |\n| OpenAI | `from_openai()` | `OpenAI` | BlackBox |\n| Anthropic | `from_anthropic()` | `Anthropic` | BlackBox |\n| Google Gemini | `from_gemini()` | `Gemini` | BlackBox |\n| Ollama | `from_ollama()` | `Ollama` | BlackBox |\n| llama.cpp | `from_llamacpp()` | `Llamacpp` | Steerable |\n| MLX-LM | `from_mlxlm()` | `MlxLm` | Steerable |\n| vLLM | `from_vllm()` | `VLLM` | Steerable |\n| SGLang | `from_sglang()` | `SGLang` | Steerable |\n\nSource: [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n\n## FSM Compilation Pipeline\n\nThe FSM (Finite State Machine) compilation is the core mechanism that enables structured generation for steerable models.\n\n```mermaid\ngraph LR\n A[\"Python Type
(Pydantic, Literal, etc.)\"] --> B[\"JSON Schema\"]\n B --> C[\"Regex Pattern\"]\n C --> D[\"FSM
(via interegular)\"]\n D --> E[\"Token Mask\"]\n \n style A fill:#e1f5ff\n style E fill:#fff3e1\n```\n\n### Type System Transformations\n\nThe type system in `outlines/types/dsl.py` handles the conversion pipeline:\n\n1. **Python Types → JSON Schema**: Pydantic models and Python types are converted to JSON Schema\n2. **JSON Schema → Regex**: Complex types are converted to regex patterns\n3. **Regex → FSM**: The `outlines-core` library (using `interegular`) compiles regex to finite state machines\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Key Design Decisions\n\n### 1. FSM-Based Constraints\n\nFor local models where logits are accessible, constraints compile to finite state machines that track valid next tokens. The FSM maintains a current state and can determine, for any given state, which tokens are valid next tokens.\n\nThis approach provides:\n- **Complete coverage**: All valid continuations are allowed, all invalid are blocked\n- **Efficiency**: State transitions are O(1) lookup\n- **Correctness**: Guarantees well-formed outputs matching the schema\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 2. Token-Level Control\n\nConstraints apply at the token level, not the character level. This is critical because LLMs generate text token-by-token, and constraining at the character level would be both inefficient and potentially incorrect.\n\n```mermaid\ngraph TD\n A[\"Token 1: 'Hello'\"] --> B[\"Token 2: 'World'\"]\n B --> C[\"Token 3: '!'\"]\n \n subgraph FSM_State\n D[\"Current State: q3\"]\n E[\"Valid Tokens: [END, '!', '.']\"]\n end\n \n D --> E\n```\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 3. Lazy Compilation\n\nFSM compilation is deferred until first use and the resulting FSM is cached persistently. This avoids expensive compilation overhead on module import or model loading, and allows the system to handle dynamic type specifications efficiently.\n\nSource: [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 4. Type-Driven API\n\nPython types are the primary interface for specifying constraints, aligning with how developers already specify data structures in Python code.\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass Review(BaseModel):\n sentiment: Literal[\"positive\", \"negative\", \"neutral\"]\n confidence: float\n\nresult = model(\"I love this product!\", Review)\n```\n\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Exception Handling Architecture\n\nOutlines defines a hierarchical exception system for consistent error handling across providers.\n\n```mermaid\ngraph TD\n A[\"Exception\"] --> B[\"OutlinesError\"]\n B --> C[\"APIError\"]\n \n C --> D[\"AuthenticationError\"]\n C --> E[\"PermissionDeniedError\"]\n C --> F[\"NotFoundError\"]\n C --> G[\"RateLimitError\"]\n C --> H[\"BadRequestError\"]\n C --> I[\"ServerError\"]\n \n B --> J[\"ProviderResponseError\"]\n B --> K[\"GenerationError\"]\n```\n\nAll public exceptions inherit from `OutlinesError` → `APIError` (for provider errors). The `normalize_provider_exception` function converts raw provider SDK exceptions into appropriate Outlines types.\n\nSource: [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## Generation Workflow\n\nThe following diagram illustrates the complete generation workflow for a structured output request:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Model\n participant Generator\n participant TypeSystem\n participant FSM\n participant Guide\n participant LogitsProcessor\n \n User->>Model: model(prompt, OutputType)\n Model->>Generator: create Generator(model, OutputType)\n Generator->>TypeSystem: convert(OutputType)\n TypeSystem->>FSM: compile to FSM\n Note over FSM: FSM cached after first use\n \n loop For each token\n Model->>LogitsProcessor: logits\n LogitsProcessor->>Guide: get valid tokens\n Guide->>LogitsProcessor: token mask\n LogitsProcessor->>Model: masked logits\n Model->>Guide: next token\n Guide->>FSM: transition state\n end\n \n Generator->>Model: final output\n Model-->>User: structured result\n```\n\nSource: [outlines/generator.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/generator.py)\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Backend System\n\nThe backend system provides abstraction for different inference engines used with steerable models.\n\n```python\n# Backend selection via generator\ngenerator = Generator(model, OutputType, backend=\"transformers\")\n\n# Or via direct model call\nresult = model(prompt, OutputType, backend=\"vllm\")\n```\n\nAvailable backends for steerable models include:\n\n| Backend | Description |\n|---------|-------------|\n| `transformers` | Hugging Face Transformers library |\n| `vllm` | vLLM inference engine |\n| `sglang` | SGLang runtime |\n| `llamacpp` | llama.cpp inference |\n\nSource: [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Version 1 Interface Changes\n\nOutlines v1 introduced significant architectural changes to the model interface:\n\n### Before (v0)\n```python\nfrom outlines import generate, models\n\nmodel = models.openai(\"gpt-4o\")\ngenerator = generate.json(model, Character)\nresult = generator(\"Create a character\")\n```\n\n### After (v1)\n```python\nfrom outlines import from_openai\n\nmodel = from_openai(OpenAI(), \"gpt-4o\")\nresult = model(\"Create a character\", Character)\n```\n\nKey changes:\n- Models can now be called directly with prompt and output type\n- All models have a `stream()` method callable by users\n- `Generator` class provides reusable generation with caching\n- `Application` class replaces deprecated `Function` class for templated generation\n\nSource: [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Documentation Architecture\n\nThe project uses MkDocs with automatic API reference generation:\n\n```mermaid\ngraph TD\n A[\"scripts/gen_ref_pages.py\"] --> B[\"mkdocs.yml\"]\n B --> C[\"mkdocs-gen-files\"]\n C --> D[\"API Reference Pages\"]\n \n subgraph \"Documentation Structure\"\n E[\"docs/guide/\"] --> F[\"User Guides\"]\n G[\"docs/features/\"] --> H[\"Feature Documentation\"]\n I[\"api_reference/\"] --> J[\"Auto-generated API Docs\"]\n end\n```\n\nSource: [scripts/gen_ref_pages.py](https://github.com/dottxt-ai/outlines/blob/main/scripts/gen_ref_pages.py)\nSource: [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n\n---\n\n\n\n## Core Concepts\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture), [Output Types Overview](#page-output-types), [Structured Generation Backends](#page-backends)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n- [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n \n\n# Core Concepts\n\nOutlines is a structured text generation library that guarantees type-safe, constrained outputs from Large Language Models (LLMs). Rather than post-processing model outputs with fragile parsing logic, Outlines integrates constraint enforcement directly into the generation process, ensuring outputs conform to specified structures from the moment generation begins.\n\n## Architecture Overview\n\nOutlines employs a layered architecture that transforms high-level type specifications into low-level token masking operations. The system bridges the gap between Python type annotations and the token-level mechanics of language model inference.\n\n```mermaid\ngraph TD\n A[User API
outlines.models] --> B[Generator Classes
SteerableGenerator
BlackBoxGenerator]\n B --> C[Type System
Pydantic → JsonSchema → Regex]\n C --> D[FSM Compilation
outlines-core
regex → FSM via interegular]\n D --> E[Guide System
processors/guide.py
FSM state management]\n E --> F[Logits Processing
processors/structured.py
token masking]\n F --> G[Model Providers
transformers
OpenAI
Anthropic
etc.]\n```\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Layer Stack\n\n### 1. User API Layer (`outlines.models`)\n\nThe topmost layer provides the primary interface for developers. Users instantiate a model using provider-specific functions and call it directly with prompts and output types.\n\n**Source:** [llm.txt:architecture](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 2. Generator Classes\n\nTwo generator abstractions handle different model categories:\n\n| Generator Class | Model Type | Control Level | Constraint Application |\n|-----------------|------------|---------------|------------------------|\n| `SteerableGenerator` | Local models (transformers, llama.cpp) | Full logits control | FSM-based token masking |\n| `BlackBoxGenerator` | API models (OpenAI, Anthropic) | API-level constraints | Provider's native structured output |\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 3. Type System (`types/dsl.py`)\n\nThe type system transforms Python types into machine-processable constraints:\n\n```mermaid\ngraph LR\n A[Pydantic Models
BaseModel] --> B[JSON Schema]\n B --> C[Regex Pattern]\n C --> D[Finite State Machine]\n```\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 4. FSM Compilation (`outlines-core`)\n\nThe compilation layer converts regex patterns into finite state machines using the `interegular` library. This transformation enables efficient constraint checking at token boundaries.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 5. Guide System (`processors/guide.py`)\n\nThe guide system manages FSM state transitions during generation. It tracks which states are valid given the current token sequence and determines allowable next tokens.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### 6. Logits Processing (`processors/structured.py`)\n\nFor steerable models, this layer applies token masking by setting probabilities of invalid tokens to negative infinity, ensuring they cannot be selected during sampling.\n\n**Source:** [llm.txt:layer-stack](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n## Key Design Decisions\n\n### FSM-Based Constraints\n\nFor local models where Outlines controls the sampling process, constraints compile to finite state machines. These FSMs track valid next tokens at each generation step, enabling efficient constraint enforcement without enumerating all possible sequences.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Provider Abstraction\n\nThe same constraint system works across different model providers:\n\n- **Local models**: Outlines controls sampling, applying FSM-based masking\n- **API models**: Outlines uses provider-native structured output support when available, or falls back to completion with validation\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Lazy Compilation\n\nFSM compilation occurs on first use and results are cached persistently. This approach avoids upfront compilation overhead while ensuring subsequent generations with the same type are fast.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Token-Level Control\n\nConstraints apply at the token level rather than the character level. This design choice ensures that the constraint system works correctly with subword tokenization schemes used by modern language models.\n\n**Source:** [llm.txt:key-design-decisions](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n\n### Type-Driven API\n\nPython types serve as the primary interface for specifying output constraints. This design choice provides:\n\n- Familiar syntax for Python developers\n- Static type checking support\n- Integration with Pydantic for complex validation\n- Support for Literal types, enums, and nested structures\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n## Model Integration\n\n### Base Model Architecture\n\nThe `Model` base class defines the contract for all provider implementations. Concrete implementations inherit from this base and implement provider-specific input/output handling.\n\n```python\n# Simplified base class structure\nclass Model(ABC):\n @abstractmethod\n def __call__(self, prompt, output_type):\n pass\n \n @abstractmethod\n def stream(self, prompt, output_type):\n pass\n```\n\n**Source:** [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n### Supported Providers\n\nOutlines provides integrations for multiple model providers:\n\n| Provider | Function | Control Type |\n|----------|----------|--------------|\n| OpenAI | `from_openai()` | BlackBox |\n| Anthropic | `from_anthropic()` | BlackBox |\n| Google Gemini | `from_gemini()` | BlackBox |\n| Transformers | `from_transformers()` | Steerable |\n| Ollama | `from_ollama()` | Steerable/BlackBox |\n| vLLM | `from_vllm()` | Steerable |\n| SGLang | `from_sglang()` | Steerable |\n| Llama.cpp | `from_llamacpp()` | Steerable |\n\n**Source:** [mkdocs.yml:navigation](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n\n### Gemini Integration Example\n\n```python\nfrom outlines import from_gemini\n\nclient = Client() # google.genai.Client\nmodel = from_gemini(client, model_name=\"gemini-pro\")\nresult = model(\"What is 2 + 2?\", int) # Returns 4\n```\n\n**Source:** [outlines/models/gemini.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/gemini.py)\n\n## Error Handling\n\n### Exception Hierarchy\n\nOutlines defines a comprehensive exception hierarchy for structured error handling:\n\n```\nOutlinesError (base)\n├── APIError (provider API errors)\n│ ├── AuthenticationError\n│ ├── PermissionDeniedError\n│ ├── NotFoundError\n│ ├── RateLimitError\n│ ├── BadRequestError\n│ └── ServerError\n├── APITimeoutError\n├── APIConnectionError\n├── ProviderResponseError\n└── GenerationError\n```\n\n**Source:** [outlines/exceptions.py:outlines-exception-hierarchy](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n### Exception Normalization\n\nThe `normalize_provider_exception` function converts raw provider SDK exceptions into appropriate Outlines types, preserving original exceptions for debugging:\n\n```python\ndef normalize_provider_exception(\n exception: Exception, \n provider: Optional[str] = None\n) -> OutlinesError\n```\n\n**Source:** [outlines/exceptions.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/exceptions.py)\n\n## Output Types\n\n### Basic Python Types\n\nOutlines supports primitive Python types as output specifications:\n\n| Type | Generated Output |\n|------|------------------|\n| `int` | Integer numbers |\n| `float` | Decimal numbers |\n| `bool` | True/False |\n| `str` | Arbitrary strings |\n\n**Source:** [README.md:quickstart](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Literal Types\n\nFor constrained choices, `Literal` types specify exact valid outputs:\n\n```python\nfrom typing import Literal\n\nresult = model(\"Is this positive or negative?\", Literal[\"Positive\", \"Negative\", \"Neutral\"])\n```\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Pydantic Models\n\nComplex nested structures use Pydantic for specification:\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n```\n\n**Source:** [README.md:complex-structures](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Regex Patterns\n\nThe `Regex` type constrains outputs to match specific patterns:\n\n```python\nfrom outlines.types import Regex\n\nphone_number = model(\"Contact:\", Regex(r\"\\d{3}-\\d{3}-\\d{4}\"))\n```\n\n**Source:** [outlines/release_note.md:regex-dsl](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n### JSON Schema\n\nFor language-agnostic type definitions, `JsonSchema` accepts raw JSON Schema strings:\n\n```python\nfrom outlines.types import JsonSchema\n\nschema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2?\", JsonSchema(schema))\n```\n\n**Source:** [outlines/release_note.md:regex-dsl](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Generator Pattern\n\nThe `Generator` class encapsulates reusable generation with a fixed output type:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n\nmodel = from_transformers(...)\ngenerator = Generator(model, Character)\n\n# Reuse without recompiling the output type\nresult1 = generator(\"Create a male character\", {\"gender\": \"male\"})\nresult2 = generator(\"Create a female character\", {\"gender\": \"female\"})\n```\n\n**Source:** [outlines/release_note.md:generator-constructor](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## Application Pattern\n\nThe `Application` class combines templates with structured output types:\n\n```python\nfrom outlines import Application, Template\n\nclass Character(BaseModel):\n name: str\n\ntemplate = Template.from_string(\"Create a {{ gender }} character.\")\napp = Application(template, Character)\n\nresult = app(model, {\"gender\": \"female\"})\n```\n\n**Source:** [outlines/release_note.md:application-class](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n\n## The Outlines Philosophy\n\nOutlines mirrors Python's type system philosophy: specify what you want, and the system ensures it. Rather than validating and parsing outputs after generation, Outlines guarantees structurally valid outputs from the start.\n\n**Source:** [README.md:philosophy](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n\n### Design Principles\n\n1. **Constraint at generation time**: Validity is enforced during token selection, not after\n2. **Fail fast**: Invalid outputs are impossible by construction\n3. **Provider independence**: Same API works across all supported models\n4. **Type familiarity**: Use standard Python types and Pydantic models\n\n**Source:** [README.md:why-outlines](https://github.com/dottext-ai/outlines/blob/main/README.md)\n\n---\n\n\n\n## Structured Generation Backends\n\n### Related Pages\n\nRelated topics: [System Architecture](#page-architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n- [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n- [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n- [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n- [docs/features/advanced/backends.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/advanced/backends.md)\n \n\n# Structured Generation Backends\n\nStructured Generation Backends are the underlying engine components in Outlines that handle the compilation of structured constraints (such as JSON schemas and regular expressions) into efficient token-level generation guides. These backends abstract away the complexity of constraint compilation, providing a unified interface for steering language model outputs while allowing users to choose the most appropriate implementation for their use case.\n\n## Architecture Overview\n\nOutlines supports multiple backend implementations for structured generation, each with different trade-offs in terms of performance, memory usage, and feature support. The backend system follows a pluggable architecture where users can select or let Outlines choose the optimal backend automatically.\n\n```mermaid\ngraph TD\n User[User Code] --> API[Outlines API]\n API --> Backends[Backend Selection]\n Backends --> Core[OutlinesCore]\n Backends --> XGrammar[XGrammar]\n Backends --> LLGuidance[LLGuidance]\n \n Core --> FSM[FSM Compilation]\n XGrammar --> XG_Engine[XGrammar Engine]\n LLGuidance --> LL_Engine[LLGuidance Engine]\n \n FSM --> Guide[Generation Guide]\n XG_Engine --> Guide\n LL_Engine --> Guide\n \n Guide --> Tokens[Token Masking]\n Tokens --> Model[Language Model]\n Model --> Output[Structured Output]\n```\n\nThe backend system sits between the high-level Outlines API and the underlying language model, transforming structural constraints into actionable token-level guidance during generation. Source: [outlines/backends/__init__.py:1-60](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Available Backends\n\nOutlines provides three main backend implementations for structured generation, each optimized for different scenarios.\n\n| Backend | Module | Description |\n|---------|--------|-------------|\n| **OutlinesCore** | `outlines_core` | Default backend using the interegular library for FSM compilation |\n| **XGrammar** | `xgrammar` | Optimized backend using the xgrammar library for faster compilation |\n| **LLGuidance** | `llguidance` | Specialized backend using llguidance for high-performance generation |\n\nSource: [outlines/backends/__init__.py:20-30](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### OutlinesCore Backend\n\nThe OutlinesCore backend is the default implementation that uses the `interegular` library to compile regular expressions and JSON schemas into Finite State Machines (FSMs). This backend provides comprehensive support for all Outlines features and serves as the reference implementation.\n\nKey characteristics:\n- Pure Python implementation using interegular for regex parsing\n- Persistent caching of compiled FSMs\n- Full support for JSON schemas and regex constraints\n- Memory-efficient for moderate-sized schemas\n\nThe backend converts structured constraints through the following pipeline:\n1. Parse the JSON schema or regex pattern\n2. Compile to an intermediate FSM representation using interegular\n3. Optimize the FSM for token-level generation\n4. Cache the compiled result for reuse\n\nSource: [outlines/backends/outlines_core.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/outlines_core.py)\n\n### XGrammar Backend\n\nThe XGrammar backend provides an optimized implementation that leverages the xgrammar library for faster constraint compilation. This backend is particularly useful for applications requiring quick iteration cycles where compilation speed matters.\n\nKey characteristics:\n- Faster compilation times compared to OutlinesCore\n- Optimized token masking operations\n- Good balance between performance and memory usage\n- Requires xgrammar as an additional dependency\n\nSource: [outlines/backends/xgrammar.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/xgrammar.py)\n\n### LLGuidance Backend\n\nThe LLGuidance backend uses the llguidance library to provide high-performance structured generation. This backend is designed for production workloads where generation speed is critical.\n\nKey characteristics:\n- Maximum generation throughput\n- Low-latency token selection\n- Specialized for constrained generation scenarios\n- Requires llguidance as an additional dependency\n\nSource: [outlines/backends/llguidance.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/llguidance.py)\n\n## Backend Selection\n\nOutlines provides two mechanisms for backend selection: automatic default selection and explicit user specification.\n\n### Default Backend Configuration\n\nWhen no backend is explicitly specified, Outlines uses the default backends defined in the configuration:\n\n| Constraint Type | Default Backend |\n|----------------|-----------------|\n| JSON Schema | `outlines_core` |\n| Regex | `outlines_core` |\n\nSource: [outlines/backends/__init__.py:25-28](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### Explicit Backend Selection\n\nUsers can specify a backend explicitly using the `backend` parameter when calling model generation methods:\n\n```python\nimport outlines\nfrom pydantic import BaseModel\n\nclass Person(BaseModel):\n name: str\n age: int\n\n# Use specific backend\nresult = model(\"Create a person\", Person, backend=\"xgrammar\")\n```\n\nBackend names are case-insensitive and map to the following implementations:\n\n- `\"outlines_core\"` or `\"outlinescore\"`: OutlinesCore backend\n- `\"xgrammar\"`: XGrammar backend\n- `\"llguidance\"`: LLGuidance backend\n\nSource: [outlines/backends/__init__.py:55-58](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Backend Factory Functions\n\nThe backend system provides factory functions that create the appropriate logits processor based on the constraint type and selected backend.\n\n### JSON Schema Logits Processor\n\nThe `get_json_schema_logits_processor` function creates a logits processor for JSON schema constraints:\n\n```python\ndef get_json_schema_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n json_schema: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a JSON schema.\n \n Parameters\n ----------\n backend_name : str | None\n The name of the backend to use.\n model : Model\n The Outlines model of the user.\n json_schema : str\n The JSON schema to create a logits processor from.\n \n Returns\n -------\n LogitsProcessorType\n The logits processor.\n \"\"\"\n backend = _get_backend(\n backend_name or JSON_SCHEMA_DEFAULT_BACKEND,\n model,\n )\n return backend.get_json_schema_logits_processor(json_schema)\n```\n\nSource: [outlines/backends/__init__.py:58-85](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n### Regex Logits Processor\n\nThe `get_regex_logits_processor` function creates a logits processor for regex constraints:\n\n```python\ndef get_regex_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n regex: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a regex.\n \n Parameters\n ----------\n backend_name : str | None\n The name of the backend to use.\n model : Model\n The Outlines model of the user.\n regex : str\n The regex to create a logits processor from.\n \n Returns\n -------\n LogitsProcessorType\n The logits processor.\n \"\"\"\n backend = _get_backend(\n backend_name or REGEX_DEFAULT_BACKEND,\n model,\n )\n return backend.get_regex_logits_processor(regex)\n```\n\nSource: [outlines/backends/__init__.py:87-115](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Backend Interface\n\nAll backends implement a common interface defined in the base backend class. This ensures consistent behavior across different implementations.\n\n### Base Backend Methods\n\nEach backend must implement the following methods:\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `get_json_schema_logits_processor(json_schema)` | Create processor for JSON schema constraints | `LogitsProcessorType` |\n| `get_regex_logits_processor(regex)` | Create processor for regex constraints | `LogitsProcessorType` |\n\nSource: [outlines/backends/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/base.py)\n\n### Backend Registry\n\nThe backend system uses a registry pattern to manage available implementations:\n\n```python\nBACKENDS = {\n \"outlines_core\": OutlinesCoreBackend,\n \"xgrammar\": XGrammarBackend,\n \"llguidance\": LLGuidanceBackend,\n}\n\ndef _get_backend(backend_name: str, model: SteerableModel):\n \"\"\"Get a backend instance by name.\"\"\"\n if backend_name == \"outlines_core\":\n return OutlinesCoreBackend(model)\n elif backend_name == \"xgrammar\":\n return XGrammarBackend(model)\n elif backend_name == \"llguidance\":\n return LLGuidanceBackend(model)\n else:\n raise ValueError(f\"Backend {backend_name} not supported\")\n```\n\nSource: [outlines/backends/__init__.py:30-45](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Integration with Model Classes\n\nBackends are invoked through the Generator class and model calling interfaces. When a user specifies an output type, the appropriate backend is selected to create a logits processor that guides the generation.\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Model as Model Class\n participant Generator as Generator\n participant Backend as Backend Selection\n participant Processor as Logits Processor\n \n User->>Model: model(prompt, output_type, backend=\"xgrammar\")\n Model->>Generator: Generator(model, output_type, backend)\n Generator->>Backend: _get_backend(backend_name, model)\n Backend->>Processor: get_json_schema_logits_processor(json_schema)\n Processor-->>Generator: logits_processor\n Generator-->>User: response\n```\n\nThe `stream` and `batch` methods on model classes also support backend specification:\n\n```python\n# Direct model calling with backend\nresult = model(\"prompt\", MySchema, backend=\"llguidance\")\n\n# Streaming with backend\nasync for chunk in model.stream(\"prompt\", MySchema, backend=\"xgrammar\"):\n print(chunk)\n\n# Batch processing with backend\nresults = await model.batch([\"prompt1\", \"prompt2\"], MySchema, backend=\"llguidance\")\n```\n\nSource: [outlines/models/base.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/base.py)\n\n## Error Handling\n\nThe backend system provides clear error messages when an unsupported backend is requested:\n\n```python\nraise ValueError(f\"Backend {backend_name} not supported\")\n```\n\nThis ensures users receive actionable feedback when misconfiguring the backend selection.\n\nSource: [outlines/backends/__init__.py:43-45](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n\n## Choosing a Backend\n\nThe following flowchart helps users select the appropriate backend for their use case:\n\n```mermaid\ngraph TD\n Start[Select Backend] --> NeedSpeed{Need Maximum
Generation Speed?}\n \n NeedSpeed -->|Yes| IsLLG{Available:
llguidance?}\n NeedSpeed -->|No| NeedCompile{Need Fast
Compilation?}\n \n IsLLG -->|Yes| UseLLG[Use llguidance]\n IsLLG -->|No| NeedCompile\n \n NeedCompile -->|Yes| IsXG{Available:
xgrammar?}\n NeedCompile -->|No| UseCore[Use OutlinesCore
Default]\n \n IsXG -->|Yes| UseXG[Use xgrammar]\n IsXG -->|No| UseCore\n```\n\n### Backend Selection Guidelines\n\n| Use Case | Recommended Backend |\n|----------|--------------------|\n| Development and testing | OutlinesCore (default) |\n| Fast iteration, quick schema changes | XGrammar |\n| Production, high-throughput requirements | LLGuidance |\n| Memory-constrained environments | OutlinesCore |\n| Latency-critical applications | LLGuidance |\n\n## Dependencies\n\nBackends may require additional Python packages beyond the core Outlines installation:\n\n| Backend | Required Package | Installation |\n|---------|-----------------|--------------|\n| OutlinesCore | `outlines-core` | Included with `pip install outlines` |\n| XGrammar | `xgrammar` | `pip install xgrammar` |\n| LLGuidance | `llguidance` | `pip install llguidance` |\n\n## Configuration Integration\n\nBackends can be configured globally through Outlines configuration files or environment variables. The backend selection is determined in the following order of precedence:\n\n1. Explicit `backend` parameter in the API call (highest priority)\n2. Default backend for the constraint type (lowest priority)\n\nThis allows users to set system-wide defaults while maintaining the flexibility to override per-call.\n\n---\n\n\n\n## Output Types Overview\n\n### Related Pages\n\nRelated topics: [JSON Schema and Pydantic Support](#page-json-schemas), [Regex Patterns](#page-regex-patterns)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/types/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/__init__.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [mkdocs.yml](https://github.com/dottxt-ai/outlines/blob/main/mkdocs.yml)\n \n\n# Output Types Overview\n\nOutlines provides a comprehensive type system for structured generation with Large Language Models (LLMs). Output types define the expected structure of generated text, and Outlines ensures that generated outputs match these specifications exactly during inference.\n\n## Purpose and Scope\n\nOutput types in Outlines serve as the primary interface for specifying constraints on LLM outputs. Rather than attempting to parse and fix invalid outputs after generation, Outlines enforces structure during the generation process itself. This approach eliminates fragile parsing logic and guarantees valid outputs on the first attempt.\n\nThe type system supports various complexity levels:\n\n| Type Category | Examples | Use Case |\n|---------------|----------|----------|\n| Basic Python | `int`, `float`, `str` | Simple values |\n| Literal Types | `Literal[\"Yes\", \"No\"]` | Enumerated choices |\n| Pydantic Models | `BaseModel` subclasses | Complex nested structures |\n| Regex Patterns | `Regex(...)`, `JsonSchema(...)` | Custom format constraints |\n| Context-Free Grammars | `CFG(...)` | Formal language definitions |\n\nSource: [README.md:1-20]()\n\n## Architecture\n\n### Type Conversion Pipeline\n\nOutlines converts output types into finite state machines (FSMs) that guide token selection during generation. This conversion follows a layered approach:\n\n```mermaid\ngraph TD\n A[Python Type / Pydantic Model] --> B[JSON Schema]\n B --> C[Regex Pattern]\n C --> D[FSM / State Machine]\n D --> E[Token Masking Guide]\n E --> F[Constrained Generation]\n \n G[DSL Terms] --> C\n H[CFG Grammar] --> C\n```\n\nThe type system handles three primary conversion pathways:\n\n1. **Python Types to Terms**: Basic types (`int`, `str`, `float`) and `Literal` types convert to intermediate `Term` representations\n2. **Pydantic Models to JSON Schema**: Complex models generate JSON Schema definitions\n3. **Terms to Regex**: All intermediate representations ultimately convert to regex patterns\n\nSource: [outlines/types/dsl.py:1-30]()\n\n### Core Components\n\n| Component | File Location | Responsibility |\n|-----------|---------------|----------------|\n| Term Classes | `outlines/types/dsl.py` | Define regex DSL elements |\n| JSON Schema Utilities | `outlines/types/json_schema_utils.py` | Pydantic to schema conversion |\n| Type Adapters | `outlines/types/utils.py` | Type introspection helpers |\n| FSM Compilation | `outlines-core` package | Regex to finite state machines |\n\nSource: [llm.txt:1-50]()\n\n## Basic Python Types\n\nOutlines supports native Python types as output specifications. These types are automatically converted to appropriate constraints.\n\n### Supported Types\n\n```python\nimport outlines\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = outlines.from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Integer output\ntemperature = model(\"What's the boiling point of water in Celsius?\", int)\nprint(temperature) # 100\n\n# String output (constrained format)\nname = model(\"Generate a valid email address\", str)\n```\n\n| Type | Constraint Applied |\n|------|-------------------|\n| `int` | Matches integer patterns |\n| `float` | Matches decimal numbers |\n| `str` | General text with type hints |\n\nSource: [README.md:45-60]()\n\n### Literal Types\n\n`Literal` types define exact enumerated values the model can output:\n\n```python\nfrom typing import Literal\n\nsentiment = model(\n \"Analyze: 'This product completely changed my life!'\",\n Literal[\"Positive\", \"Negative\", \"Neutral\"]\n)\nprint(sentiment) # \"Positive\"\n```\n\nThis approach is ideal for classification tasks, yes/no questions, and any scenario requiring outputs from a fixed set of options.\n\nSource: [README.md:50-55]()\n\n## Pydantic Models\n\nFor complex structured outputs, Pydantic models provide a declarative interface to define nested schemas with validation.\n\n### Defining Models\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nreview = model(\"Review the latest iPhone\", ProductReview)\n```\n\n### Model Conversion Process\n\n```mermaid\ngraph LR\n A[Pydantic BaseModel] --> B[JSON Schema]\n B --> C[Regex via interegular]\n C --> D[FSM]\n D --> E[Guided Generation]\n \n F[TypeAdapter] --> A\n G[GetJsonSchemaHandler] --> B\n```\n\nThe conversion process uses Pydantic's schema generation hooks:\n\n```python\nfrom pydantic import BaseModel, GetCoreSchemaHandler\nfrom pydantic.json_schema import JsonSchemaValue\nfrom pydantic_core import core_schema as cs\n\nclass CustomType(BaseModel):\n @classmethod\n def __get_pydantic_core_schema__(\n cls, \n source_type: Any, \n handler: GetCoreSchemaHandler\n ) -> cs.CoreSchema:\n return cs.string_schema(\n pattern=r\"^[A-Z]{2}\\d{4}$\" # Format: XX0000\n )\n```\n\nSource: [outlines/types/dsl.py:40-80]()\n\n## Regular Expression DSL\n\nThe Regex DSL provides fine-grained control over output formats through composable term classes.\n\n### Term Classes\n\n| Term Class | Description | Example |\n|------------|-------------|---------|\n| `Regex` | Base regex wrapper | `Regex(r\"\\d{3}-\\d{4}\")` |\n| `String` | Literal string match | `String(\"yes\")` |\n| `Integer` | Integer numbers | `Integer()` |\n| `Alternatives` | Choice between patterns | `either(pattern1, pattern2)` |\n| `KleeneStar` | Zero or more repetitions | `repeat(pattern)` |\n| `Optional` | Optional pattern | `optional(pattern)` |\n\nSource: [outlines/types/dsl.py:20-60]()\n\n### Building Complex Patterns\n\n```python\nfrom outlines.types import either, optional, at_least, integer\n\n# Phone number pattern\nphone = either(\n Regex(r\"\\d{3}-\\d{3}-\\d{4}\"),\n Regex(r\"\\(\\d{3}\\) \\d{3}-\\d{4}\")\n)\n\n# Complex format with optional parts\ndate_format = Sequence(\n integer(), # Year\n literal(\"-\"),\n at_least(integer(), 1), # At least one month\n optional(literal(\"-\") + at_least(integer(), 1)) # Optional day\n)\n```\n\n### Term Functions\n\nThe DSL includes utility functions for pattern composition:\n\n- `either(*terms)`: Match any one of multiple terms\n- `optional(term)`: Make a pattern optional\n- `at_least(term, n)`: Require at least n repetitions\n- `one_of(*choices)`: Synonym for `either`\n- `literal(text)`: Match exact text\n\nSource: [outlines/release_note.md:40-80]()\n\n## JsonSchema Type\n\nThe `JsonSchema` type allows direct use of JSON Schema definitions for complex validation:\n\n```python\nfrom outlines.types import JsonSchema\n\njson_schema = '''\n{\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\"type\": \"number\"},\n \"confidence\": {\"type\": \"number\", \"minimum\": 0, \"maximum\": 1}\n },\n \"required\": [\"answer\"]\n}\n'''\n\nresult = model(\"What's 2 + 2? Respond in JSON.\", JsonSchema(json_schema))\n```\n\nThis approach is useful when:\n\n- Migrating existing JSON Schema definitions\n- Working with API specifications (OpenAPI, etc.)\n- Defining schemas separately from code\n\nSource: [outlines/release_note.md:50-65]()\n\n## Context-Free Grammars\n\nOutlines supports Context-Free Grammars (CFG) for formal language generation:\n\n```python\nfrom outlines.types import CFG\n\ngrammar = CFG(\"\"\"\n expression ::= number op number\n op ::= \"+\" | \"-\" | \"*\" | \"/\"\n number ::= [0-9]+\n\"\"\")\n\nmath_result = model(\"Calculate 5 + 3\", grammar)\n```\n\nCFGs are particularly valuable for:\n\n- Programming language generation\n- Mathematical expression evaluation\n- Structured domain-specific languages\n\nSource: [outlines/release_note.md:60-70]()\n\n## Union Types\n\nUnion types enable conditional or alternative output structures:\n\n```python\nfrom typing import Union\n\nclass SuccessResponse(BaseModel):\n data: str\n timestamp: str\n\nUnknownResponse = Literal[\"I don't know\", \"Unable to determine\"]\n\nResponse = Union[SuccessResponse, UnknownResponse]\n\nresult = model(\"What is the capital of France?\", Response)\n```\n\n### Handling Incomplete Data\n\nUnion types excel at scenarios where partial information is acceptable:\n\n```python\nclass EventInfo(BaseModel):\n name: str\n date: str\n location: str\n\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\nresult = model(\n \"Extract event details: 'Join us for the meeting next week!'\",\n EventResponse\n)\n```\n\nSource: [README.md:100-120]()\n\n## Generator Integration\n\nThe `Generator` class encapsulates output types for reusable constrained generation:\n\n```python\nfrom outlines import Generator, from_transformers\nfrom pydantic import BaseModel\n\nclass Character(BaseModel):\n name: str\n species: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\ncharacter_generator = Generator(model, Character)\nresult = character_generator(\"Create a fantasy character\")\n```\n\nBenefits of using generators:\n\n| Feature | Benefit |\n|---------|---------|\n| Cached compilation | FSM compiled once, reused across calls |\n| Type inference | Output type specified at construction |\n| Consistent behavior | Same constraints applied to all generations |\n\nSource: [outlines/release_note.md:20-40]()\n\n## Type System Internals\n\n### Conversion Pipeline Details\n\n```mermaid\ngraph TD\n subgraph \"Type Definition\"\n A[Pydantic / Python Type] --> B[Term Representation]\n B --> C[Regex Pattern]\n end\n \n subgraph \"Compilation\"\n C --> D[FSM via interegular]\n D --> E[Cached FSM]\n end\n \n subgraph \"Generation\"\n E --> F[Guide Processor]\n F --> G[Token Masking]\n G --> H[Constrained Sampling]\n end\n```\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `outlines/types/__init__.py` | Public API exports |\n| `outlines/types/dsl.py` | Term classes and regex DSL |\n| `outlines/types/json_schema_utils.py` | Schema conversion utilities |\n| `outlines/types/utils.py` | Type introspection helpers |\n\nSource: [llm.txt:30-60]()\n\n## Best Practices\n\n### Choosing Output Types\n\n1. **Use Literal types** for classification and yes/no responses\n2. **Use Python primitives** (`int`, `float`) for simple numerical outputs\n3. **Use Pydantic models** for complex, nested structures\n4. **Use Regex DSL** when you need precise format control\n5. **Use CFG** for formal language generation\n\n### Performance Considerations\n\n| Complexity | Compilation Time | Runtime Overhead |\n|------------|------------------|------------------|\n| Literal types | Minimal | Negligible |\n| Simple regex | Low | Low |\n| Pydantic models | Moderate | Moderate |\n| Complex grammars | Higher | Higher |\n\nFSM compilation happens once on first use and is cached for subsequent calls, minimizing repeated overhead.\n\nSource: [llm.txt:40-50]()\n\n## Summary\n\nOutlines' output types system provides a unified, Pythonic interface for structured generation:\n\n- **Type-driven API**: Python types, Pydantic models, and custom DSLs\n- **Guaranteed validity**: Constraints enforced during generation, not after\n- **Flexible composition**: Union types, regex patterns, and grammars\n- **Performance optimized**: FSM caching and lazy compilation\n\nThe type system transforms high-level type specifications into optimized finite state machines, enabling reliable structured generation across diverse LLM providers.\n\n---\n\n\n\n## JSON Schema and Pydantic Support\n\n### Related Pages\n\nRelated topics: [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/types/json_schema_utils.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/json_schema_utils.py)\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/backends/__init__.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/backends/__init__.py)\n- [outlines/models/vllm_offline.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/models/vllm_offline.py)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n \n\n# JSON Schema and Pydantic Support\n\nOutlines provides robust support for JSON Schema and Pydantic models as first-class output type specifications. This enables developers to define complex structured output schemas using familiar Python type annotations, which are then compiled into efficient finite state machines (FSMs) for guided text generation.\n\n## Overview\n\nThe JSON Schema and Pydantic support in Outlines serves three primary purposes:\n\n1. **Type Definition** - Allows users to define output structures using Python-native type hints\n2. **Schema Conversion** - Provides bidirectional conversion between JSON Schema, Pydantic, TypedDict, and dataclass representations\n3. **Constraint Compilation** - Transforms schema definitions into regular expressions and FSMs for guided generation\n\nSource: [outlines/types/dsl.py:1-30]()\n\n## Architecture\n\n### Layer Stack for Structured Output\n\n```mermaid\ngraph TD\n A[User API: Pydantic Model / JSON Schema] --> B[Type System: python_types_to_terms]\n B --> C[JsonSchema Term / CFG Term]\n C --> D[Regex Compilation: to_regex]\n D --> E[FSM Generation via outlines-core]\n E --> F[Logits Processor: Token Masking]\n F --> G[Model Providers]\n \n H[Pydantic / TypedDict / Dataclass] -->|json_schema_dict_to_pydantic| B\n I[JSON Schema String] -->|JsonSchema class| B\n```\n\nThe type system in Outlines follows a layered architecture where Python types are progressively converted into machine-executable constraints:\n\n| Layer | Component | Responsibility |\n|-------|-----------|----------------|\n| User API | Pydantic models, JSON Schema | Define desired output structure |\n| Type System | `python_types_to_terms` | Convert Python types to Term instances |\n| Schema Representation | `JsonSchema`, `CFG` classes | Represent constraints as Terms |\n| Regex Compilation | `to_regex` | Transform Terms to regular expressions |\n| FSM Generation | outlines-core (interegular) | Convert regex to finite state machine |\n| Generation Control | Logits Processors | Mask invalid tokens during generation |\n\nSource: [outlines/types/dsl.py:46-80]()\n\n## JsonSchema Class\n\nThe `JsonSchema` class is the core abstraction for representing JSON Schema-based output types.\n\n### Class Definition\n\n```python\nclass JsonSchema(Term):\n \"\"\"Represents a JSON Schema constraint for structured generation.\"\"\"\n \n def __init__(self, schema: Union[str, dict], whitespace_pattern: Optional[str] = None):\n \"\"\"\n Args:\n schema: JSON Schema as string or dict\n whitespace_pattern: Optional regex for whitespace handling\n \"\"\"\n```\n\n### Key Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `to_format(target_type)` | Convert schema to Pydantic, TypedDict, or dataclass | Converted type or raises ValueError |\n| `from_file(path)` | Create JsonSchema from .json file | `JsonSchema` instance |\n| `_display_node()` | Get string representation | `str` |\n\nSource: [outlines/types/dsl.py:50-90]()\n\n### Schema Conversion\n\nThe `to_format` method supports converting JSON Schema to multiple Python type formats:\n\n```python\ndef to_format(self, target_types: List[str]) -> Any:\n \"\"\"Convert JSON Schema to target format(s).\n \n Supported targets: 'pydantic', 'typeddict', 'dataclass', 'str', 'dict'\n \"\"\"\n```\n\nThis method iterates through the requested target types and attempts conversion, returning the first successful result.\n\nSource: [outlines/types/dsl.py:55-80]()\n\n### Schema Validation and Comparison\n\n```python\ndef __eq__(self, other) -> bool:\n \"\"\"Compare two JsonSchema instances by parsing and comparing their contents.\"\"\"\n self_dict = json.loads(self.schema)\n other_dict = json.loads(other.schema)\n return self_dict == other_dict\n```\n\nSource: [outlines/types/dsl.py:100-108]()\n\n## JSON Schema Utilities\n\nThe `json_schema_utils.py` module provides bidirectional conversion between JSON Schema and Python type systems.\n\n### Schema Type Mapping\n\nJSON Schema types are mapped to Python types as follows:\n\n| JSON Schema Type | Python Type |\n|-----------------|-------------|\n| `string` | `str` |\n| `integer` | `int` |\n| `number` | `float` |\n| `boolean` | `bool` |\n| `array` | `List[item_type]` |\n| `object` | Pydantic / TypedDict / Dataclass |\n\nSource: [outlines/types/json_schema_utils.py:1-50]()\n\n### Conversion Functions\n\n#### json_schema_dict_to_pydantic\n\nConverts a JSON Schema dictionary to a Pydantic model:\n\n```python\ndef json_schema_dict_to_pydantic(\n schema: dict,\n name: Optional[str] = None\n) -> Type[BaseModel]:\n \"\"\"Convert JSON Schema dict to Pydantic BaseModel.\n \n Args:\n schema: JSON Schema dictionary\n name: Optional name for the model\n \n Returns:\n Pydantic BaseModel class\n \"\"\"\n```\n\n#### json_schema_dict_to_typeddict\n\nConverts JSON Schema to a TypedDict:\n\n```python\ndef json_schema_dict_to_typeddict(\n schema: dict,\n name: Optional[str] = None\n) -> _TypedDictMeta:\n \"\"\"Convert JSON Schema dict to TypedDict class.\"\"\"\n```\n\nThe conversion process:\n1. Extracts `required` fields from schema\n2. Maps `properties` to typed annotations\n3. Optional fields are wrapped with `Optional[]`\n4. Recursively handles nested objects\n\nSource: [outlines/types/json_schema_utils.py:80-120]()\n\n#### json_schema_dict_to_dataclass\n\nConverts JSON Schema to a dataclass:\n\n```python\ndef json_schema_dict_to_dataclass(\n schema: dict,\n name: Optional[str] = None\n) -> type:\n \"\"\"Convert JSON Schema dict to dataclass.\"\"\"\n```\n\n### schema_type_to_python\n\nRecursively converts JSON Schema type definitions to Python types:\n\n```python\ndef schema_type_to_python(\n schema: dict,\n caller_target_type: str = \"pydantic\"\n) -> Any:\n \"\"\"Convert JSON Schema type to Python type.\n \n Args:\n schema: JSON Schema dict or nested schema\n caller_target_type: Target format ('pydantic', 'typeddict', 'dataclass')\n \"\"\"\n```\n\nSource: [outlines/types/json_schema_utils.py:40-75]()\n\n## Backend Integration\n\nDifferent inference backends handle JSON Schema constraints through specialized logits processors.\n\n### Backend Selection\n\n```mermaid\ngraph LR\n A[Model Instance] --> B[_get_backend]\n B --> C{Backend Name}\n C -->|outlines_core| D[OutlinesCoreBackend]\n C -->|xgrammar| E[XGrammarBackend]\n C -->|llguidance| F[LLGuidanceBackend]\n \n D --> G[get_json_schema_logits_processor]\n E --> G\n F --> G\n```\n\nThe `get_json_schema_logits_processor` function creates the appropriate processor:\n\n```python\ndef get_json_schema_logits_processor(\n backend_name: str | None,\n model: SteerableModel,\n json_schema: str,\n) -> LogitsProcessorType:\n \"\"\"Create a logits processor from a JSON schema.\"\"\"\n backend = _get_backend(\n backend_name or JSON_SCHEMA_DEFAULT_BACKEND,\n model,\n )\n return backend.get_json_schema_logits_processor(json_schema)\n```\n\nSource: [outlines/backends/__init__.py:1-50]()\n\n### VLLM Offline Backend\n\nThe VLLM offline backend converts JsonSchema terms to vLLM's `GuidedDecodingParams`:\n\n```python\ndef _get_guided_decoding_params(self, output_type) -> dict:\n \"\"\"Convert output type to guided decoding parameters.\"\"\"\n if output_type is None:\n return {}\n\n term = python_types_to_terms(output_type)\n if isinstance(term, CFG):\n return {\"grammar\": term.definition}\n elif isinstance(term, JsonSchema):\n guided_decoding_params = {\"json\": json.loads(term.schema)}\n if term.whitespace_pattern:\n guided_decoding_params[\"whitespace_pattern\"] = term.whitespace_pattern\n return guided_decoding_params\n else:\n return {\"regex\": to_regex(term)}\n```\n\nSource: [outlines/models/vllm_offline.py:50-80]()\n\n## Usage Patterns\n\n### Basic Pydantic Model Usage\n\n```python\nfrom pydantic import BaseModel\nfrom enum import Enum\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nclass Rating(Enum):\n poor = 1\n fair = 2\n good = 3\n excellent = 4\n\nclass ProductReview(BaseModel):\n rating: Rating\n pros: list[str]\n cons: list[str]\n summary: str\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nreview = model(\"Amazing laptop! Great battery life, fast processor.\", ProductReview)\n```\n\nSource: [README.md:1-50]()\n\n### Using json_schema Function\n\n```python\nimport outlines\n\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"age\": {\"type\": \"integer\"},\n \"email\": {\"type\": \"string\", \"format\": \"email\"}\n },\n \"required\": [\"name\", \"email\"]\n}\n\nresult = model(\"Generate a user profile\", outlines.json_schema(schema))\n```\n\n### Union Types for Flexible Output\n\n```python\nfrom typing import Union, List, Literal\nfrom pydantic import BaseModel\n\nclass EventInfo(BaseModel):\n name: str\n date: str\n location: str\n\nEventResponse = Union[EventInfo, Literal[\"I don't know\"]]\n\nresult = model(\"What event is mentioned?\", EventResponse)\n```\n\n## Type System Functions\n\nThe DSL module provides utility functions for type checking and conversion:\n\n### Type Check Functions\n\n| Function | Purpose |\n|----------|---------|\n| `is_int(t)` | Check if type is `int` |\n| `is_float(t)` | Check if type is `float` |\n| `is_str(t)` | Check if type is `str` |\n| `is_bool(t)` | Check if type is `bool` |\n| `is_datetime(t)` | Check if type is datetime |\n| `is_date(t)` | Check if type is date |\n| `is_time(t)` | Check if type is time |\n| `is_pydantic_model(t)` | Check if type is Pydantic BaseModel |\n| `is_enum(t)` | Check if type is Enum |\n| `is_literal(t)` | Check if type is Literal |\n| `is_union(t)` | Check if type is Union |\n| `is_typing_list(t)` | Check if type is List |\n| `is_typed_dict(t)` | Check if type is TypedDict |\n\nSource: [outlines/types/dsl.py:80-150]()\n\n### python_types_to_terms\n\nThe main conversion function that transforms Python types into Term instances:\n\n```python\ndef python_types_to_terms(\n output_type,\n whitespace_pattern: Optional[str] = None\n) -> Term:\n \"\"\"Convert Python types to Term instances for guided generation.\n \n Handles:\n - Primitive types (int, float, str, bool)\n - Collections (List, Dict, Tuple)\n - Pydantic models\n - Enums and Literals\n - Union types\n - JSON Schema strings\n - TypedDict and dataclasses\n \"\"\"\n```\n\nSource: [outlines/types/dsl.py:200-280]()\n\n## Error Handling\n\n### Schema Conversion Failures\n\nWhen schema conversion fails, Outlines provides informative warnings:\n\n```python\nexcept Exception as e: # pragma: no cover\n warnings.warn(\n f\"Cannot convert schema type {type(schema)} to {target_type}: {e}\"\n )\n continue\n```\n\nIf no valid conversion is found, a ValueError is raised:\n\n```python\nraise ValueError(\n f\"Cannot convert schema type {type(schema)} to any of the target \"\n f\"types {target_types}\"\n)\n```\n\nSource: [outlines/types/dsl.py:75-82]()\n\n## Best Practices\n\n1. **Use Pydantic for Complex Schemas** - Pydantic models provide validation and IDE autocomplete\n2. **Define Required Fields** - JSON Schema `required` array ensures critical fields are generated\n3. **Use Optional for Nullable Fields** - Mark non-required fields with `Optional[]` or `= None`\n4. **Leverage Union Types** - Return fallback values when data is incomplete\n5. **Cache Compiled FSMs** - Outlines caches compiled state machines for reuse\n\n## Related Components\n\n- **CFG Support** - Context-free grammar constraints for complex syntax\n- **Regex DSL** - Direct regular expression specifications\n- **Template System** - Jinja-based prompt templating\n- **Generator Class** - Reusable generator objects with pre-compiled constraints\n\n---\n\n\n\n## Regex Patterns\n\n### Related Pages\n\nRelated topics: [Output Types Overview](#page-output-types)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [outlines/types/dsl.py](https://github.com/dottxt-ai/outlines/blob/main/outlines/types/dsl.py)\n- [outlines/release_note.md](https://github.com/dottxt-ai/outlines/blob/main/outlines/release_note.md)\n- [README.md](https://github.com/dottxt-ai/outlines/blob/main/README.md)\n- [llm.txt](https://github.com/dottxt-ai/outlines/blob/main/llm.txt)\n- [docs/features/utility/regex_dsl.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/utility/regex_dsl.md)\n- [docs/features/core/output_types.md](https://github.com/dottxt-ai/outlines/blob/main/docs/features/core/output_types.md)\n \n\n# Regex Patterns\n\nRegex patterns in Outlines provide a powerful Domain-Specific Language (DSL) for defining structured output constraints. The regex DSL allows developers to build complex pattern constraints by composing simple terms, which are then compiled into finite state machines (FSMs) that guide the language model's token generation process.\n\nThe core insight behind Outlines' regex support is that instead of generating text and hoping it matches a format, Outlines makes it impossible for the model to generate invalid outputs by masking invalid tokens during generation. Source: [llm.txt:1-10]()\n\n## Overview\n\nOutlines supports regex patterns at multiple levels of abstraction:\n\n1. **Direct Regex Patterns**: Use `Regex` class to define patterns that can be used as Pydantic field types\n2. **Regex DSL**: Compose complex patterns using term functions like `either`, `optional`, `at_least`, and integer/string helpers\n3. **JSON Schema Integration**: `JsonSchema` term accepts JSON schema strings and converts them to regex constraints\n4. **Context-Free Grammars**: `CFG` term provides grammar-based constraints for more complex languages\n\nSource: [outlines/release_note.md:1-20]()\n\n### Type Conversion Pipeline\n\nThe regex system follows a well-defined conversion pipeline:\n\n```\nPydantic Model / Python Type → Term DSL → Regex → FSM → Token Masking\n```\n\nThis pipeline ensures that high-level type specifications are progressively transformed into low-level token constraints that the generation process can enforce.\n\nSource: [llm.txt:1-15]()\n\n## The Term Classes\n\nThe `Term` class hierarchy forms the foundation of Outlines' regex DSL. All terms implement a common interface that supports composition operations and conversion to regex patterns.\n\nSource: [outlines/types/dsl.py:1-30]()\n\n### Core Term Classes\n\n| Term Class | Description | Standalone Usage |\n|------------|-------------|------------------|\n| `Regex` | Represents a raw regex pattern | Yes |\n| `String` | Literal string matching | Yes |\n| `JsonSchema` | JSON schema to regex conversion | Yes |\n| `CFG` | Context-free grammar constraints | Yes |\n| `Sequence` | Concatenation of multiple terms | No |\n| `Alternatives` | Choice between multiple terms | No |\n| `KleeneStar` | Zero or more repetitions | No |\n| `KleenePlus` | One or more repetitions | No |\n| `Optional` | Zero or one occurrence | No |\n\nSource: [outlines/types/dsl.py:30-80]()\n\n### Regex Class\n\nThe `Regex` class is a Pydantic-compatible type that represents a regular expression pattern. It can be used directly as a field type in Pydantic models.\n\n```python\nfrom outlines.types import Regex\nfrom pydantic import BaseModel\n\nage_type = Regex(\"[0-9]+\")\n\nclass User(BaseModel):\n name: str\n age: age_type\n```\n\nSource: [outlines/types/dsl.py:85-95]()\n\nThe `Regex` class provides the following composition operators:\n\n| Operator | Method | Description |\n|----------|--------|-------------|\n| `+` | `__add__` | Concatenate patterns (sequence) |\n| `\\|` | `__or__` | Create alternatives (choice) |\n| `r+` | `__radd__` | Right-side concatenation |\n| `r|` | `__ror__` | Right-side alternatives |\n\nSource: [outlines/types/dsl.py:97-115]()\n\n### JsonSchema Term\n\nThe `JsonSchema` term accepts a JSON schema string and converts it into regex constraints. This allows seamless integration with existing JSON schema definitions.\n\n```python\nfrom outlines import from_transformers\nfrom outlines.types import JsonSchema\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\njson_schema = '{\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"number\"}}}'\nresult = model(\"What's 2 + 2? Respond in JSON\", JsonSchema(json_schema))\n```\n\nSource: [outlines/release_note.md:1-25]()\n\n### CFG Term\n\nThe `CFG` (Context-Free Grammar) term allows definition of constraints using context-free grammar notation. This is useful for complex languages where regex alone is insufficient.\n\nSource: [outlines/types/dsl.py:75-80]()\n\n## Regex DSL Functions\n\nThe regex DSL provides utility functions for building complex patterns by combining simpler terms.\n\n### Composition Functions\n\n| Function | Description |\n|----------|-------------|\n| `either(*terms)` | Create alternatives from multiple terms |\n| `optional(term)` | Make a term optional (zero or one) |\n| `at_least(n, term)` | Require at least n occurrences |\n| `integer()` | Match integer patterns |\n| `float()` | Match floating-point number patterns |\n| `boolean()` | Match boolean patterns |\n\nSource: [outlines/release_note.md:1-30]()\n\n### Building Complex Patterns\n\nThe following example demonstrates building a complex regex pattern using the DSL:\n\n```python\nfrom outlines import from_transformers\nfrom outlines.types import at_least, either, integer, optional\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\n# Build a pattern that matches email-like strings\npattern = either(\"user@example.com\", \"admin@company.org\")\n```\n\nSource: [outlines/release_note.md:25-35]()\n\n## Architecture\n\n### FSM Compilation Flow\n\n```mermaid\ngraph TD\n A[User Pattern Definition] --> B[Pydantic Model / Regex DSL]\n B --> C[JSON Schema Extraction]\n C --> D[Regex Generation]\n D --> E[FSM Compilation via interegular]\n E --> F[Token-Level Constraints]\n F --> G[Logits Masking during Generation]\n G --> H[Valid Output Generation]\n```\n\nSource: [llm.txt:15-25]()\n\n### Layer Stack\n\nThe regex system integrates with Outlines' layered architecture:\n\n```\nUser API (outlines.models)\n ↓\nGenerator Classes (SteerableGenerator, BlackBoxGenerator)\n ↓\nType System (types/dsl.py: Pydantic → JsonSchema → Regex)\n ↓\nFSM Compilation (outlines-core: regex → FSM via interegular)\n ↓\nGuide System (processors/guide.py: FSM state management)\n ↓\nLogits Processing (processors/structured.py: token masking)\n ↓\nModel Providers (transformers, OpenAI, etc.)\n```\n\nSource: [llm.txt:30-45]()\n\n## Usage Patterns\n\n### Simple Classification with Literals\n\nWhile not strictly regex, Outlines uses the same constraint infrastructure for literal choices:\n\n```python\nfrom typing import Literal\nfrom outlines import from_transformers\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = from_transformers(\n AutoModelForCausalLM.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\"),\n AutoTokenizer.from_pretrained(\"microsoft/Phi-3-mini-4k-instruct\")\n)\n\nresult = model(\"Pizza or burger\", Literal[\"pizza\", \"burger\"])\n```\n\nSource: [outlines/release_note.md:60-75]()\n\n### Regex as Pydantic Field Types\n\nFor more complex validation, use `Regex` as a Pydantic field type:\n\n```python\nfrom outlines.types import Regex\nfrom pydantic import BaseModel\n\nclass ProductCode(BaseModel):\n code: Regex(r\"^[A-Z]{3}-[0-9]{4}$\")\n```\n\nThe `Regex` class implements Pydantic's schema generation and validation interfaces:\n\n| Method | Purpose |\n|--------|---------|\n| `__get_validator__` | Pydantic validator for input validation |\n| `__get_pydantic_core_schema__` | Core schema for Pydantic v2 integration |\n| `__get_pydantic_json_schema__` | JSON schema generation |\n\nSource: [outlines/types/dsl.py:117-130]()\n\n## Integration with Type System\n\n### Python Types to Terms Conversion\n\nThe `python_types_to_terms` function maps Python types to their corresponding Term representations:\n\n| Python Type | Term Equivalent |\n|-------------|------------------|\n| `int` | `integer()` |\n| `float` | `float()` |\n| `str` | `string` |\n| `bool` | `boolean()` |\n| `List[T]` | Pattern for lists |\n| `Literal[...]` | Alternatives |\n\nSource: [outlines/types/dsl.py:1-60]()\n\n### Schema Utilities\n\nThe type system includes utilities for converting between different schema formats:\n\n- `json_schema_dict_to_pydantic()`: Convert JSON schema to Pydantic model\n- `json_schema_dict_to_typeddict()`: Convert to TypedDict\n- `json_schema_dict_to_dataclass()`: Convert to dataclass\n\nSource: [outlines/types/dsl.py:50-55]()\n\n## Key Design Decisions\n\n### Token-Level Control\n\nOutlines' regex constraints operate at the token level, not character level. This means:\n\n1. FSMs are compiled from regex patterns using the `interegular` library\n2. State transitions map (state, token) → next_state\n3. For each state, invalid tokens are masked by setting their logits to negative infinity\n\nSource: [llm.txt:45-50]()\n\n### Lazy Compilation\n\nFSMs are compiled on first use and cached persistently. This ensures:\n- Initial overhead is minimal\n- Repeated generation with the same schema is fast\n- Memory is efficiently managed through caching\n\nSource: [llm.txt:50-55]()\n\n## API Reference\n\n### Regex Class\n\n```python\nclass Regex(Term):\n def __init__(self, pattern: str):\n \"\"\"Initialize with a regex pattern string.\"\"\"\n \n def __add__(self, other: Term) -> Sequence:\n \"\"\"Concatenate patterns.\"\"\"\n \n def __or__(self, other: Term) -> Alternatives:\n \"\"\"Create alternatives.\"\"\"\n \n def validate(self, value: Any) -> Any:\n \"\"\"Validate a value against the pattern.\"\"\"\n```\n\n### DSL Functions\n\n```python\ndef either(*terms: Term) -> Alternatives:\n \"\"\"Create alternatives from multiple terms.\"\"\"\n \ndef optional(term: Term) -> Term:\n \"\"\"Make a term optional (zero or one occurrence).\"\"\"\n \ndef at_least(n: int, term: Term) -> Term:\n \"\"\"Require at least n occurrences.\"\"\"\n \ndef integer() -> Term:\n \"\"\"Match integer patterns.\"\"\"\n \ndef boolean() -> Term:\n \"\"\"Match boolean patterns.\"\"\"\n```\n\nSource: [outlines/types/dsl.py:30-75]()\n\n## Best Practices\n\n1. **Pre-compile complex patterns**: If using the same pattern multiple times, consider using the `Generator` class to cache the FSM compilation\n\n2. **Use Pydantic models for complex structures**: JSON schema conversion provides a cleaner API for nested objects\n\n3. **Leverage composition operators**: Build complex patterns from simple terms using `+` and `|` operators\n\n4. **Test patterns separately**: Validate regex patterns independently before using them in generation\n\n## See Also\n\n- [Output Types Documentation](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/)\n- [Regex DSL Guide](https://dottxt-ai.github.io/outlines/latest/features/utility/regex_dsl/)\n- [Generator Documentation](https://dottxt-ai.github.io/outlines/latest/features/core/generator/)\n- [Context-Free Grammars](https://dottxt-ai.github.io/outlines/latest/features/core/output_types/#context-free-grammars)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: dottxt-ai/outlines\n\nSummary: Found 30 potential pitfall items; 5 are high/blocking. Highest priority: installation - 来源证据：[Feature] Streaming structured generation with partial validation.\n\n## 1. installation · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. maintenance · 来源证据：Add more custom types\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. security_permissions · 来源证据：Add function calling and MCP support\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. security_permissions · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. installation · 失败模式：installation: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: Developers may fail before the first successful local run: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: OWASP ASI06 memory poisoning defense for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_aafbb33fe2e219639553f4d4275e0223 | https://github.com/dottxt-ai/outlines/issues/1864 | Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n## 7. installation · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- User impact: Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes\n\n## 8. installation · 失败模式：installation: Outlines v1.2.6\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.6\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 9. installation · 失败模式：installation: Outlines v1.2.8\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.8\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 10. installation · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 12. maintenance · 失败模式：migration: Outlines v1.2.10\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.10\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 13. maintenance · 失败模式：migration: Outlines v1.3.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.3.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 14. maintenance · 来源证据：Complex structure makes output empty\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 16. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 18. security_permissions · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. security_permissions · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. capability · 失败模式：capability: Add function calling and MCP support\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- User impact: Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 21. capability · 失败模式：capability: Add more custom types\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add more custom types\n- User impact: Developers may hit a documented source-backed failure mode: Add more custom types\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add more custom types. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 22. capability · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set. Context: Observed when using python, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_77f306218d1269b169d6fd1a5669ca47 | https://github.com/dottxt-ai/outlines/issues/1847 | TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n## 23. capability · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 24. capability · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 25. capability · 失败模式：conceptual: Complex structure makes output empty\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- User impact: Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 26. runtime · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add streaming support for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 27. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 28. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 29. maintenance · 失败模式：maintenance: Outlines v1.2.12\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.12\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 30. maintenance · 失败模式：maintenance: Outlines v1.2.9\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.9\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.9. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: dottxt-ai/outlines\n\nSummary: Found 30 potential pitfall items; 5 are high/blocking. Highest priority: installation - 来源证据：[Feature] Streaming structured generation with partial validation.\n\n## 1. installation · 来源证据：[Feature] Streaming structured generation with partial validation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Streaming structured generation with partial validation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_dc85cb063a664cf28645f478ac7de3e4 | https://github.com/dottxt-ai/outlines/issues/1856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. configuration · 来源证据：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_275e7b7e47ef449aa9f5aebb987eaf63 | https://github.com/dottxt-ai/outlines/issues/1859 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. maintenance · 来源证据：Add more custom types\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add more custom types\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_e9b8049cf33648f59be1398a828cfd91 | https://github.com/dottxt-ai/outlines/issues/1303 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. security_permissions · 来源证据：Add function calling and MCP support\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add function calling and MCP support\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_cc2063bf4a764510890d6ab8b2218e10 | https://github.com/dottxt-ai/outlines/issues/1626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. security_permissions · 来源证据：[Feature Request] Add streaming support for structured generation\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add streaming support for structured generation\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0a0ce1410e93475594f5dafc93f9613a | https://github.com/dottxt-ai/outlines/issues/1842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. installation · 失败模式：installation: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: Developers may fail before the first successful local run: Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: OWASP ASI06 memory poisoning defense for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_aafbb33fe2e219639553f4d4275e0223 | https://github.com/dottxt-ai/outlines/issues/1864 | Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n## 7. installation · 失败模式：installation: Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Incompatibility with vllm==0.19 because of some api changes\n- User impact: Developers may fail before the first successful local run: Incompatibility with vllm==0.19 because of some api changes\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Incompatibility with vllm==0.19 because of some api changes. Context: Observed when using python, cuda\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_9f23e49bc91e3f8af003ddcdedec3e72 | https://github.com/dottxt-ai/outlines/issues/1854 | Incompatibility with vllm==0.19 because of some api changes\n\n## 8. installation · 失败模式：installation: Outlines v1.2.6\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.6\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.6\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.6. Context: Observed during installation or first-run setup.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e917f6640a48bc54b76cbbbfcfd2b346 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.6 | Outlines v1.2.6\n\n## 9. installation · 失败模式：installation: Outlines v1.2.8\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: Outlines v1.2.8\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.8\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.8. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_802eb50b3a54cd87f585ac14e899b4bc | https://github.com/dottxt-ai/outlines/releases/tag/1.2.8 | Outlines v1.2.8\n\n## 10. installation · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for structured generation\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5fe257116a4b481dbd938b2c0d9ad949 | https://github.com/dottxt-ai/outlines/issues/1864 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:615403340 | https://github.com/dottxt-ai/outlines | README/documentation is current enough for a first validation pass.\n\n## 12. maintenance · 失败模式：migration: Outlines v1.2.10\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.2.10\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.10\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.10. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_75fc0fce3c200ef68083c6815dfb1b11 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.10 | Outlines v1.2.10\n\n## 13. maintenance · 失败模式：migration: Outlines v1.3.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Outlines v1.3.0\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.3.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.3.0. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_82ad3c4174eb532f8038cfd014a85efb | https://github.com/dottxt-ai/outlines/releases/tag/1.3.0 | Outlines v1.3.0\n\n## 14. maintenance · 来源证据：Complex structure makes output empty\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Complex structure makes output empty\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_f19de4e577a341e8a7d5cc9289b1b5c9 | https://github.com/dottxt-ai/outlines/issues/1861 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | last_activity_observed missing\n\n## 16. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 17. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:615403340 | https://github.com/dottxt-ai/outlines | no_demo; severity=medium\n\n## 18. security_permissions · 来源证据：Incompatibility with vllm==0.19 because of some api changes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Incompatibility with vllm==0.19 because of some api changes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_45101a3eaffb4eda98b4d597dd5aca64 | https://github.com/dottxt-ai/outlines/issues/1854 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. security_permissions · 来源证据：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_85cb7bc56eb64613b9ec65e51dea90e9 | https://github.com/dottxt-ai/outlines/issues/1847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. capability · 失败模式：capability: Add function calling and MCP support\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add function calling and MCP support\n- User impact: Developers may hit a documented source-backed failure mode: Add function calling and MCP support\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add function calling and MCP support. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dfb58c522eebbd15e72f7bfbfc936335 | https://github.com/dottxt-ai/outlines/issues/1626 | Add function calling and MCP support\n\n## 21. capability · 失败模式：capability: Add more custom types\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: Add more custom types\n- User impact: Developers may hit a documented source-backed failure mode: Add more custom types\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add more custom types. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8ba5f20b34d61b76171e5fdc02fffff8 | https://github.com/dottxt-ai/outlines/issues/1303 | Add more custom types\n\n## 22. capability · 失败模式：capability: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- User impact: Developers may hit a documented source-backed failure mode: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set. Context: Observed when using python, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_77f306218d1269b169d6fd1a5669ca47 | https://github.com/dottxt-ai/outlines/issues/1847 | TransformerTokenizer reads attributes from raw backend that modern transformers doesn't set\n\n## 23. capability · 失败模式：capability: [Feature] Streaming structured generation with partial validation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: [Feature] Streaming structured generation with partial validation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature] Streaming structured generation with partial validation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Streaming structured generation with partial validation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_0990edf56e70825cebd4d6337f2e9ec7 | https://github.com/dottxt-ai/outlines/issues/1856 | [Feature] Streaming structured generation with partial validation\n\n## 24. capability · 失败模式：capability: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this capability risk before relying on the project: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- User impact: Developers may hit a documented source-backed failure mode: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_7477c33ba4e3aefcd5a822e817746461 | https://github.com/dottxt-ai/outlines/issues/1859 | 📝 Integration Proposal: CAJAL — Structured Scientific Paper Generation\n\n## 25. capability · 失败模式：conceptual: Complex structure makes output empty\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this conceptual risk before relying on the project: Complex structure makes output empty\n- User impact: Developers may hit a documented source-backed failure mode: Complex structure makes output empty\n- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_adb9b1e93b18abc454b9ec796b30af1a | https://github.com/dottxt-ai/outlines/issues/1861 | Complex structure makes output empty\n\n## 26. runtime · 失败模式：performance: [Feature Request] Add streaming support for structured generation\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this performance risk before relying on the project: [Feature Request] Add streaming support for structured generation\n- User impact: Developers may hit a documented source-backed failure mode: [Feature Request] Add streaming support for structured generation\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add streaming support for structured generation. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_f9e262951793c35ca4f0f973546df68f | https://github.com/dottxt-ai/outlines/issues/1842 | [Feature Request] Add streaming support for structured generation\n\n## 27. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | issue_or_pr_quality=unknown\n\n## 28. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:615403340 | https://github.com/dottxt-ai/outlines | release_recency=unknown\n\n## 29. maintenance · 失败模式：maintenance: Outlines v1.2.12\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.12\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.12\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.12. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_654aac443ea5eec7b12b4b1cbe602de9 | https://github.com/dottxt-ai/outlines/releases/tag/1.2.13 | Outlines v1.2.12\n\n## 30. maintenance · 失败模式：maintenance: Outlines v1.2.9\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: Developers should check this maintenance risk before relying on the project: Outlines v1.2.9\n- User impact: Upgrade or migration may change expected behavior: Outlines v1.2.9\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Outlines v1.2.9. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e26ccdb4b7c8d266e55856497effd5ae | https://github.com/dottxt-ai/outlines/releases/tag/1.2.9 | Outlines v1.2.9\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# outlines - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for dottxt-ai/outlines.\n\nProject:\n- Name: outlines\n- Repository: https://github.com/dottxt-ai/outlines\n- Summary: Structured Outputs\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Structured Outputs\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Structured Outputs\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Outlines. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quickstart Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-installation: Installation. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-core-concepts: Core Concepts. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/dottxt-ai/outlines\n- https://github.com/dottxt-ai/outlines#readme\n- README.md\n- outlines/__init__.py\n- outlines/release_note.md\n- docs/guide/getting_started.md\n- docs/guide/installation.md\n- pyproject.toml\n- environment.yml\n- docs/guide/architecture.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: dottxt-ai/outlines\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install outlines\n```\n\nSource：https://github.com/dottxt-ai/outlines#readme\n\n## Sources\n\n- repo: https://github.com/dottxt-ai/outlines\n- docs: https://github.com/dottxt-ai/outlines#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_12464c5413314f709980a9b98f4740c4"
}