{
"canonical_name": "guardrails-ai/guardrails",
"compilation_id": "pack_2b699465cee04c8d83f29bbe39104757",
"created_at": "2026-05-22T03:47:17.676302+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 guardrails-ai` 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 guardrails-ai",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_30eca47d4c774492a3214c468ad9b477"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_85e45fa2bef2a40f01fa3b66fcd9a8d9",
"canonical_name": "guardrails-ai/guardrails",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/guardrails-ai/guardrails",
"slug": "guardrails",
"source_packet_id": "phit_e9ea46b293f64b34915485deb0d15835",
"source_validation_id": "dval_4e8dcba9fe0c48c2ac835e2e5a64cd86"
},
"merchandising": {
"best_for": "需要安全审查与权限治理能力，并使用 chatgpt的用户",
"github_forks": 599,
"github_stars": 6843,
"one_liner_en": "Adding guardrails to large language models.",
"one_liner_zh": "Adding guardrails to large language models.",
"primary_category": {
"category_id": "security-permissions",
"confidence": "high",
"name_en": "Security & Permissions",
"name_zh": "安全审查与权限治理",
"reason": "curated popular coverage category matched project identity"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "guardrails",
"title_zh": "guardrails 能力包",
"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": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e9ea46b293f64b34915485deb0d15835",
"page_model": {
"artifacts": {
"artifact_slug": "guardrails",
"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 guardrails-ai",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/guardrails-ai/guardrails#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"断点恢复流程",
"开源工具"
],
"eyebrow": "安全审查与权限治理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要安全审查与权限治理能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Adding guardrails to large language models."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: OWASP ASI06 memory poisoning guard validator",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e44b7cdf7b674acf9789c9feddc13dbc | https://github.com/guardrails-ai/guardrails/issues/1488 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature request: OWASP ASI06 memory poisoning guard validator",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Portable evidence artifacts for validation outcomes",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_64ae6a0aa3324a3a9af980f2f61a5c30 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Proposal: Agent Threat Rules detection integration",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] 429 Rate Limit Error from Opting into Metrics",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3c9ae4fdd14547eea3c3a4be6ac6fb23 | https://github.com/guardrails-ai/guardrails/issues/1385 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[bug] 429 Rate Limit Error from Opting into Metrics",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[docs] Fix double logo display in pypi",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "Developers should check this security_permissions risk before relying on the project: Best-practice: litellm pin excludes patched CVE versions, unverified-jwt-decode duplication, workflow inputs interpolation",
"category": "安全/权限坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_819ae3bfce09ed33a4655a81cf59dd44 | https://github.com/guardrails-ai/guardrails/issues/1485 | Best-practice: litellm pin excludes patched CVE versions, unverified-jwt-decode duplication, workflow inputs interpolation"
],
"severity": "high",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Best-practice: litellm pin excludes patched CVE versions, unverified-jwt-decode duplication, workflow inputs interpolation. Context: Observed when using python",
"title": "失败模式：security_permissions: Best-practice: litellm pin excludes patched CVE versions, unverified-jwt-decode duplication,...",
"user_impact": "Developers may expose sensitive permissions or credentials: Best-practice: litellm pin excludes patched CVE versions, unverified-jwt-decode duplication, workflow inputs interpolation"
},
{
"body": "Developers should check this security_permissions risk before relying on the project: Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard",
"category": "安全/权限坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_2c7b3b6f6709cc847b37fb56bc9973d3 | https://github.com/guardrails-ai/guardrails/issues/1476 | Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard",
"failure_mode_cluster:github_issue | fmev_77887b77c9dabcdbce93e8b20c9a7c57 | https://github.com/guardrails-ai/guardrails/issues/1475 | Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard"
],
"severity": "high",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard. Context: Observed when using python",
"title": "失败模式：security_permissions: Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard",
"user_impact": "Developers may expose sensitive permissions or credentials: Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard"
},
{
"body": "Developers should check this security_permissions risk before relying on the project: [bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub",
"category": "安全/权限坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_70a43b34234fca351363180353991f27 | https://github.com/guardrails-ai/guardrails/issues/1479 | [bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub"
],
"severity": "high",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub. Context: Observed when using python, docker, cuda",
"title": "失败模式：security_permissions: [bug] Failures and Delayed Responses from guard.validate Method Using Different Validator wit...",
"user_impact": "Developers may expose sensitive permissions or credentials: [bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0f957598a5044976a69cdd1925dd9483 | https://github.com/guardrails-ai/guardrails/issues/1476 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature Request: OWASP ASI06 memory write validation via Agent Memory Guard",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Integration proposal: Cryptographic audit trail validator with asqav",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3f90fdd47b014d488f2782f04c75b37c | https://github.com/guardrails-ai/guardrails/issues/1479 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[bug] Failures and Delayed Responses from guard.validate Method Using Different Validator with Guardrails Hub",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "Developers should check this installation risk before relying on the project: Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_2a7dfe1829e559543fd3177ac3a0ace3 | https://github.com/guardrails-ai/guardrails/issues/1463 | Integration proposal: styxx hallucination validator (8-benchmark cross-validated)"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Integration proposal: styxx hallucination validator (8-benchmark cross-validated). Context: Observed when using python, cuda",
"title": "失败模式：installation: Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"user_impact": "Developers may fail before the first successful local run: Integration proposal: styxx hallucination validator (8-benchmark cross-validated)"
},
{
"body": "Developers should check this installation risk before relying on the project: Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_b8ff8a254ff16e4d23faa27660558c49 | https://github.com/guardrails-ai/guardrails/issues/1483 | Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+). Context: Observed during installation or first-run setup.",
"title": "失败模式：installation: Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)",
"user_impact": "Developers may fail before the first successful local run: Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 38 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 77,
"forks": 599,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 6843
},
"source_url": "https://github.com/guardrails-ai/guardrails",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Adding guardrails to large language models.",
"title": "guardrails 能力包",
"trial_prompt": "# guardrails - 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 guardrails-ai/guardrails.\n\nProject:\n- Name: guardrails\n- Repository: https://github.com/guardrails-ai/guardrails\n- Summary: Adding guardrails to large language models.\n- Host target: chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Adding guardrails to large language models.\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: Adding guardrails to large language models.\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. getting-started: Getting Started with Guardrails. Produce one small intermediate artifact and wait for confirmation.\n2. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. guard-class: Guard Class Reference. Produce one small intermediate artifact and wait for confirmation.\n4. validators: Validators System. Produce one small intermediate artifact and wait for confirmation.\n5. schema-processing: Schema Processing. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/guardrails-ai/guardrails\n- https://github.com/guardrails-ai/guardrails#readme\n- README.md\n- guardrails/__init__.py\n- guardrails/version.py\n- guardrails/guard.py\n- guardrails/async_guard.py\n- guardrails/validator_service/validator_service_base.py\n- guardrails/classes/schema/processed_schema.py\n- guardrails/schema/pydantic_schema.py\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 guard validator（https://github.com/guardrails-ai/guardrails/issues/1488）；github/github_issue: Proposal: Agent Threat Rules detection integration（https://github.com/guardrails-ai/guardrails/issues/1471）；github/github_issue: Proposal: Agent Threat Rules detection integration（https://github.com/guardrails-ai/guardrails/issues/1471）；github/github_issue: Proposal: Agent Threat Rules detection integration（https://github.com/guardrails-ai/guardrails/issues/1471）；github/github_issue: Proposal: Agent Threat Rules detection integration（https://github.com/guardrails-ai/guardrails/issues/1471）；github/github_issue: Best-practice: litellm pin excludes patched CVE versions, unverified-jwt（https://github.com/guardrails-ai/guardrails/issues/1485）；github/github_issue: Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)（https://github.com/guardrails-ai/guardrails/issues/1483）；github/github_issue: [SECURITY] Supply Chain Compromise in guardrails-ai v0.10.1 on PyPI（https://github.com/guardrails-ai/guardrails/issues/1473）；github/github_issue: [bug] 429 Rate Limit Error from Opting into Metrics（https://github.com/guardrails-ai/guardrails/issues/1385）；github/github_issue: [bug] Failures and Delayed Responses from guard.validate Method Using Di（https://github.com/guardrails-ai/guardrails/issues/1479）；github/github_issue: [feat] Attempt to repair JSON before triggering NonParseableReAsk（https://github.com/guardrails-ai/guardrails/issues/1380）；github/github_issue: Feature Request: OWASP ASI06 memory write validation via Agent Memory Gu（https://github.com/guardrails-ai/guardrails/issues/1476）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature request: OWASP ASI06 memory poisoning guard validator",
"url": "https://github.com/guardrails-ai/guardrails/issues/1488"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration",
"url": "https://github.com/guardrails-ai/guardrails/issues/1471"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration",
"url": "https://github.com/guardrails-ai/guardrails/issues/1471"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration",
"url": "https://github.com/guardrails-ai/guardrails/issues/1471"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration",
"url": "https://github.com/guardrails-ai/guardrails/issues/1471"
},
{
"kind": "github_issue",
"source": "github",
"title": "Best-practice: litellm pin excludes patched CVE versions, unverified-jwt",
"url": "https://github.com/guardrails-ai/guardrails/issues/1485"
},
{
"kind": "github_issue",
"source": "github",
"title": "Lift litellm <1.82.6 pin to allow post-incident safe releases (1.83+)",
"url": "https://github.com/guardrails-ai/guardrails/issues/1483"
},
{
"kind": "github_issue",
"source": "github",
"title": "[SECURITY] Supply Chain Compromise in guardrails-ai v0.10.1 on PyPI",
"url": "https://github.com/guardrails-ai/guardrails/issues/1473"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] 429 Rate Limit Error from Opting into Metrics",
"url": "https://github.com/guardrails-ai/guardrails/issues/1385"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Failures and Delayed Responses from guard.validate Method Using Di",
"url": "https://github.com/guardrails-ai/guardrails/issues/1479"
},
{
"kind": "github_issue",
"source": "github",
"title": "[feat] Attempt to repair JSON before triggering NonParseableReAsk",
"url": "https://github.com/guardrails-ai/guardrails/issues/1380"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feature Request: OWASP ASI06 memory write validation via Agent Memory Gu",
"url": "https://github.com/guardrails-ai/guardrails/issues/1476"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "安全审查与权限治理",
"desc": "Adding guardrails to large language models.",
"effort": "安装已验证",
"forks": 599,
"icon": "shield",
"name": "guardrails 能力包",
"risk": "可发布",
"slug": "guardrails",
"stars": 6843,
"tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"断点恢复流程",
"开源工具"
],
"thumb": "purple",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/guardrails-ai/guardrails 项目说明书\n\n生成时间：2026-05-15 16:49:27 UTC\n\n## 目录\n\n- [Getting Started with Guardrails](#getting-started)\n- [System Architecture](#system-architecture)\n- [Guard Class Reference](#guard-class)\n- [Validators System](#validators)\n- [Schema Processing](#schema-processing)\n- [Execution Pipeline](#execution-pipeline)\n- [Async and Streaming Support](#async-streaming)\n- [LLM Provider Integration](#llm-providers)\n- [Framework Integrations](#framework-integrations)\n- [Creating Custom Validators](#custom-validators)\n\n\n\n## Getting Started with Guardrails\n\n### 相关页面\n\n相关主题：[Guard Class Reference](#guard-class), [Validators System](#validators)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n \n\n# Getting Started with Guardrails\n\n## Overview\n\nGuardrails is an open-source Python library that provides validation, correction, and structural guarantees for AI/LLM applications. It enables developers to define constraints on LLM outputs and automatically validates, corrects, or re-asks the model when outputs violate those constraints. 资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\nThe library serves as a critical layer between LLM outputs and application logic, ensuring that AI-generated content meets specified quality, safety, and structural requirements.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- pip or pipx\n\n### Standard Installation\n\nInstall Guardrails from PyPI:\n\n```bash\npip install guardrails-ai\n```\n\n### Development Installation\n\nFor contributors or those who want the latest features from the main branch:\n\n```bash\n# Clone the repository\ngit clone https://github.com/guardrails-ai/guardrails.git\ncd guardrails\n\n# Install in development mode\nmake dev\n\n# Install pre-commit hooks\npre-commit install\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md), [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n## Core Concepts\n\n### Guard\n\nThe `Guard` is the central component in Guardrails. It wraps LLM calls and applies validation rules to ensure outputs meet specified constraints.\n\n```python\nfrom guardrails import Guard, OnFailAction\n\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### Validators\n\nValidators are individual constraint checks that can be applied to LLM outputs. They are installed from the Guardrails Hub or created as custom validators.\n\n```python\nfrom guardrails.hub import RegexMatch, CompetitorCheck, ToxicLanguage\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### OnFailAction\n\nActions to take when validation fails:\n\n| Action | Description |\n|--------|-------------|\n| `EXCEPTION` | Raise an exception |\n| `REASK` | Re-ask the LLM to produce valid output |\n| `FIX` | Attempt to auto-fix the output |\n| `FILTER` | Filter out invalid parts |\n| `REFRAIN` | Return nothing for invalid fields |\n\n## Quick Start Guide\n\n### Step 1: Configure Guardrails Hub CLI\n\nAfter installation, configure the Guardrails CLI:\n\n```bash\nguardrails configure\n```\n\n### Step 2: Install Required Validators\n\nInstall validators from Guardrails Hub based on your use case:\n\n```bash\n# Example: Install validators for phone number validation and competitor checking\nguardrails hub install hub://guardrails/regex_match\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### Step 3: Create a Guard\n\nCreate a Guard instance with your desired validators:\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck([\"Apple\", \"Microsoft\", \"Google\"], on_fail=OnFailAction.EXCEPTION),\n ToxicLanguage(threshold=0.5, validation_method=\"sentence\", on_fail=OnFailAction.EXCEPTION)\n)\n```\n\n### Step 4: Validate LLM Output\n\nApply the Guard to validate outputs:\n\n```python\n# Valid output - passes all validations\nguard.validate(\n \"\"\"An apple a day keeps a doctor away.\n This is good advice for keeping your health.\"\"\"\n)\n\n# Invalid output - fails validations\ntry:\n guard.validate(\n \"\"\"Shut the hell up! Apple just released a new iPhone.\"\"\"\n )\nexcept Exception as e:\n print(e)\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User Application] --> B[Guard Instance]\n B --> C[Validators Stack]\n C --> D[LLM Call]\n D --> E{Validation Pass?}\n E -->|Yes| F[Return Validated Output]\n E -->|No| G[OnFailAction Handler]\n G --> H[EXCEPTION / REASK / FIX / FILTER / REFRAIN]\n H --> I[Retry if REASK]\n I --> D\n```\n\n## Creating Guards\n\n### From RAIL String\n\nRAIL (Reliable AI Abstraction Language) is an XML-based specification for defining output constraints:\n\n```python\nfrom guardrails import Guard\n\nrail_string = '''\n\n \n \n \n \n\n'''\n\nguard = Guard.from_rail_string(rail_string)\n```\n\n资料来源：[guardrails/guard.py:45-60](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n### From Pydantic Model\n\nDefine output structure using Pydantic BaseModel:\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"Species of pet\")\n name: str = Field(description=\"a unique pet name\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\nThe Guard uses two methods to generate structured data:\n1. **Function calling**: For LLMs that support function calling\n2. **Prompt optimization**: For LLMs that don't support function calling (schema added to prompt)\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md), [guardrails/guard.py:85-115](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n## Guardrails Hub Validators\n\nThe Guardrails Hub provides pre-built validators for common use cases:\n\n| Validator | Purpose | Example Usage |\n|-----------|---------|---------------|\n| `RegexMatch` | Validate string against regex pattern | Phone number format |\n| `CompetitorCheck` | Detect mentions of competitors | Brand safety |\n| `ToxicLanguage` | Detect toxic/offensive content | Content moderation |\n| `LowerCase` | Ensure text is lowercase | Normalization |\n| `UpperCase` | Ensure text is uppercase | Normalization |\n\n### Installing Validators\n\n```bash\n# From Guardrails Hub\nguardrails hub install hub://guardrails/\n\n# With specific version\nguardrails hub install hub://guardrails/regex_match~=1.4\n```\n\n资料来源：[guardrails/hub/install.py:45-60](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## Validation Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Guard\n participant Validators\n participant LLM\n \n User->>Guard: validate(input)\n Guard->>Validators: Check constraints\n alt Validation Failed\n Validators-->>Guard: ValidationError\n Guard->>Guard: Handle OnFailAction\n alt OnFailAction.REASK\n Guard->>LLM: Request correction\n LLM-->>Guard: New response\n Guard->>Validators: Re-validate\n end\n end\n Guard-->>User: Validated output / Exception\n```\n\n## Creating Custom Validators\n\nUse the CLI to scaffold a new validator:\n\n```bash\nguardrails hub create-validator MyValidator\n```\n\nThis creates a template file with the required structure:\n\n```python\nfrom guardrails import Validator\nfrom guardrails.validators import ValidationResult, PassResult\n\nclass MyValidator(Validator):\n \"\"\"Description of what your validator does.\"\"\"\n \n def __init__(self, arg_1: str, **kwargs):\n # Initialize with custom arguments\n super().__init__(**kwargs)\n \n def validate(self, value: Any, **kwargs) -> ValidationResult:\n # Implement validation logic\n if valid:\n return PassResult()\n else:\n return FailResult()\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py:35-70](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n## Development Workflow\n\nFor contributing to Guardrails:\n\n1. **Clone and setup**:\n ```bash\n git clone https://github.com/guardrails-ai/guardrails.git\n cd guardrails\n make dev\n ```\n\n2. **Run tests**:\n ```bash\n make test\n ```\n\n3. **Format code**:\n ```bash\n make autoformat\n ```\n\n4. **Type checking**:\n ```bash\n make type\n ```\n\n5. **Update documentation**:\n ```bash\n make docs-gen\n ```\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n## Call History and Debugging\n\nThe Guard maintains a history of all calls, useful for debugging and monitoring:\n\n```python\ncall = guard.validate(\"123-456-7890\")\nprint(call.iterations) # View all iterations\nprint(call.id) # Unique call identifier\n```\n\nEach `Call` object contains:\n- `iterations`: Stack of validation iterations\n- `inputs`: Original inputs to the Guard\n- `exception`: Any exception that occurred\n\n资料来源：[guardrails/classes/history/call.py:15-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n\n## CLI Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `guardrails configure` | Configure Guardrails Hub CLI |\n| `guardrails hub install ` | Install a validator from Hub |\n| `guardrails hub create-validator ` | Create a new validator template |\n| `guardrails start` | Start the Guardrails API server |\n\n资料来源：[guardrails/cli/start.py:25-50](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py), [guardrails/cli/hub/install.py:20-45](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n\n## Common Patterns\n\n### Input and Output Guards\n\nApply different validators to input and output:\n\n```python\nguard = Guard()\n\n# Input validation\nguard.use(InputValidator(CompetitorCheck, competitors=[...]))\n\n# Output validation \nguard.use(OutputValidator(ToxicLanguage))\n```\n\n### Multiple Validators\n\nChain multiple validators on a single Guard:\n\n```python\nguard = Guard().use(\n Validator1(param1=value1),\n Validator2(param2=value2),\n Validator3()\n)\n```\n\n### Streaming Support\n\nGuardrails supports streaming responses:\n\n```python\nguard.validate(\n llm_output,\n metadata={\"stream\": True}\n)\n```\n\n## Next Steps\n\n- Explore the [Guardrails Hub](https://guardrailsai.com/hub/) for available validators\n- Read the API documentation for detailed parameter descriptions\n- Join the [Discord community](https://discord.gg/Jsey3mX98B) for support\n- Check existing issues and contribute to the project\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Getting Started with Guardrails](#getting-started), [Execution Pipeline](#execution-pipeline)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/async_guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/async_guard.py)\n- [guardrails/validator_service/validator_service_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_service/validator_service_base.py)\n- [guardrails/classes/schema/processed_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/schema/processed_schema.py)\n \n\n# System Architecture\n\n## Overview\n\nGuardrails is a Python library for validating and constraining outputs from Large Language Models (LLMs). The system provides a flexible framework for defining validation rules (validators), composing them into Guards, and applying them to LLM outputs to ensure they meet specified quality and safety criteria.\n\n资料来源：[README.md:1-20]()\n\n## High-Level Architecture\n\nThe Guardrails system consists of several key layers that work together to provide LLM output validation:\n\n```mermaid\ngraph TB\n subgraph \"Presentation Layer\"\n Guard[\"Guard Class\"]\n AsyncGuard[\"AsyncGuard Class\"]\n end\n \n subgraph \"Schema Layer\"\n ProcessedSchema[\"ProcessedSchema\"]\n RailSchema[\"RailSchema\"]\n end\n \n subgraph \"Validation Layer\"\n ValidatorService[\"ValidatorService\"]\n Validators[\"Validators\"]\n end\n \n subgraph \"Integration Layer\"\n LLMProviders[\"LLM Providers\"]\n APIClient[\"APIClient\"]\n end\n \n Guard --> ProcessedSchema\n AsyncGuard --> ProcessedSchema\n ProcessedSchema --> ValidatorService\n ValidatorService --> Validators\n Guard --> LLMProviders\n Guard --> APIClient\n```\n\n资料来源：[guardrails/guard.py:1-50]()\n\n## Core Components\n\n### Guard Class\n\nThe `Guard` class is the primary entry point for using Guardrails. It serves as a container for validators and provides methods for validating LLM outputs.\n\n#### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Validator Composition** | Chain multiple validators using `.use()` method |\n| **Schema Support** | Support for RAIL, Pydantic, and JSON Schema |\n| **LLM Integration** | Built-in support for various LLM providers |\n| **History Tracking** | Records all validation iterations and outcomes |\n| **Async Support** | Separate `AsyncGuard` class for async operations |\n\n#### Factory Methods\n\n```python\n@classmethod\ndef from_rail(cls, rail_string: str, ...) -> Guard\n@classmethod\ndef for_pydantic(cls, output_class: ModelOrListOfModels, ...) -> Guard\n```\n\nThe `Guard` class provides multiple ways to create instances:\n\n1. **`from_rail()`** - Creates a Guard from a RAIL (Rich Application Information Language) string\n2. **`for_pydantic()`** - Creates a Guard using Pydantic models to define output structure\n\n资料来源：[guardrails/guard.py:200-280]()\n\n### AsyncGuard Class\n\nThe `AsyncGuard` class provides asynchronous validation capabilities, enabling non-blocking LLM output validation for high-throughput applications.\n\n#### Key Differences from Guard\n\n| Aspect | Guard | AsyncGuard |\n|--------|-------|------------|\n| Execution | Synchronous | Asynchronous (async/await) |\n| Use Case | Standard applications | High-performance async apps |\n| API | `guard.validate()` | `await guard.avalidate()` |\n\n### Validator Service\n\nThe `ValidatorService` is the core validation engine that executes validators against input data.\n\n#### Responsibilities\n\n- Load and initialize validators\n- Execute validation pipeline\n- Handle validation failures and reasks\n- Collect and aggregate validation results\n\n```mermaid\ngraph LR\n Input[\"Input Data\"] --> ValidatorService\n ValidatorService --> V1[\"Validator 1\"]\n ValidatorService --> V2[\"Validator 2\"]\n ValidatorService --> VN[\"Validator N\"]\n V1 --> Result1[\"Result 1\"]\n V2 --> Result2[\"Result 2\"]\n VN --> ResultN[\"Result N\"]\n Result1 --> Aggregated[\"Aggregated Result\"]\n Result2 --> Aggregated\n ResultN --> Aggregated\n```\n\n资料来源：[guardrails/validator_service/validator_service_base.py:1-50]()\n\n### ProcessedSchema\n\nThe `ProcessedSchema` class handles the parsing and processing of validation schemas into an internal format that can be executed by the validator service.\n\n#### Schema Processing Flow\n\n```mermaid\ngraph TD\n RawSchema[\"Raw Schema Input\"] --> Parser[\"Schema Parser\"]\n Parser --> Processed[\"ProcessedSchema\"]\n Processed --> Serialization[\"Serialization\"]\n Serialization --> Storage[\"Storage/Caching\"]\n Processed --> Execution[\"Validation Execution\"]\n```\n\n资料来源：[guardrails/classes/schema/processed_schema.py:1-40]()\n\n## Validation Flow\n\n### Standard Validation Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Guard\n participant ProcessedSchema\n participant ValidatorService\n participant Validator\n participant LLM\n\n User->>Guard: validate(output)\n Guard->>ProcessedSchema: parse_and_validate()\n ProcessedSchema->>ValidatorService: run_validators()\n ValidatorService->>Validator: validate()\n Validator-->>ValidatorService: ValidationResult\n ValidatorService-->>ProcessedSchema: AggregatedResult\n ProcessedSchema-->>Guard: FinalResult\n Guard-->>User: Result/Exception\n```\n\n### ReAsk Flow\n\nWhen initial validation fails, the system can trigger a reask mechanism:\n\n1. Validation fails for field\n2. System generates reask prompt\n3. LLM receives reask prompt\n4. New output is validated\n5. Process repeats until valid or max iterations reached\n\n资料来源：[guardrails/guard.py:300-400]()\n\n## Schema System\n\n### Supported Schema Formats\n\n| Format | Method | Description |\n|--------|--------|-------------|\n| RAIL | `Guard.from_rail()` | XML-based schema with validators |\n| Pydantic | `Guard.for_pydantic()` | Python class-based schema |\n| JSON Schema | `json_schema_to_rail_output()` | JSON schema conversion |\n\n### RAIL Schema Processing\n\nThe `rail_schema.py` module handles conversion between different schema formats:\n\n```python\ndef json_schema_to_rail_output(\n json_schema: Dict[str, Any], \n validator_map: ValidatorMap\n) -> str:\n \"\"\"Takes a JSON Schema and converts it to the RAIL output specification.\"\"\"\n```\n\n资料来源：[guardrails/schema/rail_schema.py:60-80]()\n\n## History and Call Tracking\n\nThe `Call` class tracks each execution of a Guard, maintaining a history of all iterations:\n\n```python\nclass Call:\n iterations: Stack[Iteration] # Stack of iterations for reasks\n inputs: CallInputs # Original inputs to Guard\n exception: Optional[Exception] # Any exceptions during execution\n```\n\n#### Call Structure\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `iterations` | `Stack[Iteration]` | Each validation round and reask |\n| `inputs` | `CallInputs` | Original prompt, parameters, etc. |\n| `exception` | `Exception` | Exception if Guard execution failed |\n\n资料来源：[guardrails/classes/history/call.py:10-50]()\n\n## Integration Architecture\n\n### LLM Provider Integration\n\nGuardrails integrates with multiple LLM providers through a unified interface:\n\n```mermaid\ngraph TB\n Guard[\"Guard Class\"]\n ManifestCallable[\"ManifestCallable\"]\n LiteLLMCallable[\"LiteLLMCallable\"]\n CustomCallable[\"Custom Provider\"]\n \n Guard --> ManifestCallable\n Guard --> LiteLLMCallable\n Guard --> CustomCallable\n```\n\nSupported providers include:\n- OpenAI\n- Anthropic\n- LiteLLM (unified interface)\n- Manifest (local models)\n\n资料来源：[guardrails/llm_providers.py:1-100]()\n\n### API Client Integration\n\nThe `APIClient` enables remote Guard management:\n\n| Method | Purpose |\n|--------|---------|\n| `upsert_guard()` | Create or update a Guard on the server |\n| `fetch_guard()` | Retrieve a Guard by name |\n| `aupsert_guard()` | Async version of upsert |\n\n```python\nasync def aupsert_guard(self, guard: Guard) -> Guard:\n existing_guard = await self.afetch_guard(guard.name)\n if existing_guard:\n response = await self.ahttp_client.put(...)\n else:\n response = await self.ahttp_client.post(...)\n```\n\n资料来源：[guardrails/api_client.py:1-80]()\n\n## Hub Integration\n\n### Validator Installation\n\nThe Hub system allows dynamic installation of validators:\n\n```python\ndef install(package_uri: str, ...) -> ModuleType:\n # 1. Validate package URI\n # 2. Fetch manifest\n # 3. Download dependencies\n # 4. Install via pip\n```\n\n#### Installation Flow\n\n```mermaid\ngraph LR\n A[\"hub://guardrails/regex_match\"] --> B[\"ValidatorPackageService\"]\n B --> C[\"Fetch Manifest\"]\n C --> D[\"Install Dependencies\"]\n D --> E[\"Load Module\"]\n```\n\n资料来源：[guardrails/hub/install.py:20-60]()\n\n## CLI Architecture\n\n### Command Structure\n\n| Command | File | Purpose |\n|---------|------|---------|\n| `guardrails configure` | CLI setup | Configure Guardrails settings |\n| `guardrails hub install` | `cli/hub/install.py` | Install validators from Hub |\n| `guardrails hub create-validator` | `cli/hub/create_validator.py` | Scaffold new validators |\n| `guardrails start` | `cli/start.py` | Start Guardrails API server |\n\n资料来源：[guardrails/cli/start.py:1-50]()\n\n## Error Handling and Logging\n\n### Log Levels\n\n| Level | Value | Usage |\n|-------|-------|-------|\n| `SPAM` | 5 | Verbose debug information |\n| `VERBOSE` | 15 | Detailed execution info |\n| `NOTICE` | 25 | Important events |\n| `SUCCESS` | 35 | Successful operations |\n\n资料来源：[guardrails/cli/logger.py:1-30]()\n\n## Summary\n\nThe Guardrails architecture follows a layered approach:\n\n1. **Presentation Layer** - `Guard` and `AsyncGuard` classes provide the user-facing API\n2. **Schema Layer** - `ProcessedSchema` and `RailSchema` handle input parsing and validation rules\n3. **Validation Layer** - `ValidatorService` executes validators and aggregates results\n4. **Integration Layer** - LLM providers and API client enable seamless integration with external services\n\nThis separation of concerns allows for:\n- Flexible validator composition\n- Multiple schema format support\n- Both sync and async operation modes\n- Extensible provider integrations\n\n---\n\n\n\n## Guard Class Reference\n\n### 相关页面\n\n相关主题：[Validators System](#validators), [Schema Processing](#schema-processing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/pydantic_schema.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/classes/history/call_inputs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call_inputs.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n \n\n# Guard Class Reference\n\nThe `Guard` class is the central orchestrator in the Guardrails library, serving as the primary interface for validating, parsing, and constraining LLM outputs. It acts as a container that manages validators, output schemas, and validation outcomes while maintaining execution history.\n\n## Overview\n\nThe Guard class provides a unified API for:\n\n- Defining validation rules through RAIL XML strings or Pydantic models\n- Validating LLM outputs against specified schemas and constraints\n- Parsing raw LLM responses into structured data\n- Tracking validation history across multiple iterations and reasks\n- Configuring behavior on validation failure through `OnFailAction` strategies\n\n```mermaid\ngraph TD\n A[LLM Output] --> B[Guard Instance]\n B --> C{Validation}\n C -->|Pass| D[Validated Output]\n C -->|Fail| E{OnFailAction}\n E -->|EXCEPTION| F[Raise Exception]\n E -->|REASK| G[Reask LLM]\n E -->|FIX| H[Return Fixed Value]\n E -->|[None]| I[Return None]\n G --> A\n```\n\n## Creating Guard Instances\n\n### Factory Methods\n\nThe Guard class provides two primary factory methods for instantiation:\n\n| Method | Input Type | Use Case |\n|--------|------------|----------|\n| `Guard.from_rail()` | RAIL XML string | Complex schemas with validators |\n| `Guard.for_pydantic()` | Pydantic BaseModel | Structured data generation |\n\n### Creating from RAIL Strings\n\n```python\n@classmethod\ndef from_rail(cls, rail_string: str, *, name: str = None, description: str = None) -> \"Guard\"\n```\n\nA RAIL (Rich AI Language) string is an XML-based specification that defines:\n\n- Output schema structure\n- Field-level validators\n- Error handling behaviors\n\n```python\nfrom guardrails import Guard\n\nrail_string = \"\"\"\n\n \n\n\"\"\"\n\nguard = Guard.from_rail(rail_string, name=\"my-guard\")\n```\n\n资料来源：[guardrails/guard.py:from_rail-method](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n### Creating from Pydantic Models\n\n```python\n@classmethod\ndef for_pydantic(\n cls,\n output_class: ModelOrListOfModels,\n *,\n reask_messages: Optional[List[Dict]] = None,\n messages: Optional[List[Dict]] = None,\n name: Optional[str] = None,\n description: Optional[str] = None,\n output_formatter: Optional[Union[str, BaseFormatter]] = None,\n) -> \"Guard\"\n```\n\nThis method accepts Pydantic `BaseModel` classes and internally converts them to RAIL format for validation.\n\n```python\nfrom guardrails import Guard\nfrom pydantic import BaseModel, Field\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"Species of pet\")\n name: str = Field(description=\"a unique pet name\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[guardrails/guard.py:for_pydantic-method](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n### Internal Schema Processing\n\nBoth factory methods ultimately convert their input to an internal RAIL schema representation:\n\n```mermaid\ngraph LR\n A[Pydantic Model] -->|for_pydantic| B[JSON Schema]\n C[RAIL String] -->|from_rail| D[Schema Parser]\n B --> D\n D --> E[RAIL Schema]\n E --> F[Guard Instance]\n```\n\n资料来源：[guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n\n## Guard Configuration\n\n### Using Validators with `Guard.use()`\n\nValidators are added to a Guard instance using the `.use()` method, which chains multiple validators onto the same instance.\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch, CompetitorCheck\n\nguard = Guard().use(\n RegexMatch(regex=r\"\\d{4}\", on_fail=OnFailAction.EXCEPTION),\n CompetitorCheck([\"Apple\", \"Google\"], on_fail=OnFailAction.REASK)\n)\n```\n\n资料来源：[README.md:example-code](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## Validation Process\n\n### Core Validation Methods\n\n| Method | Purpose | Returns |\n|--------|---------|---------|\n| `validate()` | Validates LLM output against schema | `ValidationOutcome` |\n| `parse()` | Parses raw output without full validation | Parsed result |\n| `__call__()` | Combined call and validation | LLM response + validated output |\n\n### ValidationOutcome Class\n\nThe `ValidationOutcome` class encapsulates the results of validation:\n\n```python\n@dataclass\nclass ValidationOutcome:\n validation_passed: bool\n corrected_output: Any\n error_message: Optional[str]\n reasks: List[ReAsk]\n```\n\n资料来源：[guardrails/classes/validation_outcome.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation_outcome.py)\n\n### OnFailAction Enum\n\nWhen validation fails, the configured `OnFailAction` determines the behavior:\n\n| Action | Behavior |\n|--------|----------|\n| `EXCEPTION` | Raises an exception with error details |\n| `REASK` | Attempts to regenerate the LLM output with feedback |\n| `FIX` | Returns a corrected/fallback value |\n| `REFRAIN` | Returns `None` instead of output |\n| `NOOP` | Returns the original output unchanged |\n| `CUSTOM` | Uses a custom handler function |\n\n资料来源：[guardrails/types/on_fail.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/types/on_fail.py)\n\n## Call History and Iteration Tracking\n\n### Call Class Structure\n\nThe `Call` class maintains a complete history of Guard executions:\n\n```python\nclass Call:\n _id: str | None = None\n iterations: Stack[Iteration] = Field(default_factory=Stack)\n inputs: CallInputs = Field(default_factory=CallInputs)\n exception: Optional[Exception] = None\n \n @computed_field\n @property\n def id(self) -> str:\n \"\"\"Unique identifier for this Call execution.\"\"\"\n if not self._id:\n self._id = str(object_id(self))\n return self._id\n```\n\n资料来源：[guardrails/classes/history/call.py:Call-class](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n\n### Iteration Stack\n\nEach `Call` contains a stack of `Iteration` objects representing:\n\n1. The initial validation round\n2. Each subsequent reask iteration\n\n```mermaid\ngraph TD\n A[Call] --> B[Iteration 1: Initial Call]\n A --> C[Iteration 2: Reask 1]\n A --> D[Iteration N: Reask N-1]\n B --> E[Step 1: LLM Call]\n B --> F[Step 2: Validation]\n C --> G[Step: LLM Reask]\n C --> H[Step: Validation]\n```\n\n### CallInputs Data Model\n\nThe `CallInputs` class captures all inputs passed to a Guard execution:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `prompt_params` | Dict | Parameters formatted into messages |\n| `num_reasks` | int | Maximum reask attempts |\n| `metadata` | Dict | Additional runtime data |\n| `full_schema_reask` | bool | Reask entire schema vs individual fields |\n| `stream` | bool | Streaming mode flag |\n| `args` | List[Any] | Additional positional arguments |\n| `kwargs` | Dict[str, Any] | Additional keyword arguments |\n\n资料来源：[guardrails/classes/history/call_inputs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call_inputs.py)\n\n## LLM Provider Integration\n\n### PromptCallableBase Interface\n\nThe Guard class integrates with multiple LLM providers through the `PromptCallableBase` interface:\n\n```python\nclass PromptCallableBase:\n def _invoke_llm(\n self,\n text: Optional[str] = None,\n model: str = \"gpt-3.5-turbo\",\n messages: Optional[List[Dict]] = None,\n *args,\n **kwargs\n ) -> LLMResponse:\n \"\"\"Abstract method to invoke LLM.\"\"\"\n```\n\nSupported providers include:\n\n- **LiteLLM** - Unified interface to multiple LLMs\n- **Manifest** - ML model inference client\n- **OpenAI** - Direct OpenAI API integration\n\n资料来源：[guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n\n### LLM Response Structure\n\n```python\n@dataclass\nclass LLMResponse:\n output: Any # The raw LLM response\n token_usage: Optional[Dict] = None # Token consumption metrics\n model_name: Optional[str] = None # Model identifier\n```\n\n## Validator Installation via Hub\n\n### Installing Validators\n\nValidators from Guardrails Hub can be installed programmatically:\n\n```python\nfrom guardrails.hub.install import install\n\nRegexMatch = install(\"hub://guardrails/regex_match\").RegexMatch\n```\n\nThe installation process:\n\n1. Validates the package URI format\n2. Fetches the module manifest\n3. Downloads dependencies via pip\n4. Installs to site-packages\n\n资料来源：[guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## Complete Usage Example\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch, CompetitorCheck\n\n# Create a Guard with multiple validators\nguard = Guard().use(\n RegexMatch(\n regex=r\"\\d{3}-\\d{3}-\\d{4}\",\n on_fail=OnFailAction.EXCEPTION\n ),\n CompetitorCheck(\n competitors=[\"Apple\", \"Microsoft\"],\n on_fail=OnFailAction.REASK\n )\n)\n\n# Validate output\ntry:\n result = guard.validate(\"123-456-7890\")\n print(f\"Validation passed: {result.validation_passed}\")\nexcept Exception as e:\n print(f\"Validation failed: {e}\")\n\n# Access call history\ncall_history = guard.history # List of Call objects\n```\n\n## Summary\n\nThe `Guard` class serves as the central orchestrator for LLM output validation in the Guardrails library. Key responsibilities include:\n\n- **Schema Management**: Creating Guards from RAIL strings or Pydantic models\n- **Validation Orchestration**: Running validators and applying OnFailAction strategies\n- **History Tracking**: Maintaining complete execution history with iterations and steps\n- **LLM Integration**: Supporting multiple LLM providers through a unified interface\n- **Extensibility**: Allowing composition of multiple validators through the `.use()` method\n\n资料来源：[guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py), [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py), [guardrails/types/on_fail.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/types/on_fail.py)\n\n---\n\n\n\n## Validators System\n\n### 相关页面\n\n相关主题：[Guard Class Reference](#guard-class), [Creating Custom Validators](#custom-validators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/validator_service/validator_service_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_service/validator_service_base.py)\n- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n- [guardrails/telemetry/validator_tracing.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/telemetry/validator_tracing.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n \n\n# Validators System\n\n## Overview\n\nThe Validators System is a core component of the Guardrails framework that provides validation capabilities for LLM (Large Language Model) outputs. Validators are modular, composable validation units that can be attached to a `Guard` instance to enforce constraints on data before, during, or after LLM inference.\n\nValidators enable developers to:\n\n- Validate string, structured (JSON), and typed outputs from LLMs\n- Define custom failure handling policies via the `on_fail` mechanism\n- Chain multiple validators to create complex validation pipelines\n- Track validation history and results through the Call/Iteration data model\n\n## Architecture\n\n### High-Level Component Flow\n\n```mermaid\ngraph TD\n A[LLM Output] --> B[Guard.validate]\n B --> C[ValidatorService]\n C --> D[Validator 1]\n C --> E[Validator 2]\n C --> F[Validator N]\n D --> G[ValidationResult]\n E --> H[ValidationResult]\n F --> I[ValidationResult]\n G --> J[ValidationOutcome]\n H --> J\n I --> J\n J --> K[Pass or Fail with Corrections]\n```\n\n### Validator Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Initialized\n Initialized --> Running: before_run_validator\n Running --> Success: validate returns PassResult\n Running --> Failed: validate returns FailResult\n Success --> Completed: after_run_validator\n Failed --> Completed: on_fail handler applied\n Completed --> [*]\n```\n\n## Core Components\n\n### Validator Base Class\n\nValidators inherit from the base `Validator` class which provides:\n\n- Standard initialization with `on_fail` policy configuration\n- `validate(value, metadata)` method implementation contract\n- Integration with the validator service infrastructure\n- Telemetry and tracing capabilities\n\n### Validation Result Classes\n\nThe system uses two primary result types:\n\n| Class | Purpose |\n|-------|---------|\n| `PassResult` | Indicates validation succeeded |\n| `FailResult` | Indicates validation failed with error details |\n\n```mermaid\nclassDiagram\n class ValidationResult {\n <>\n }\n class PassResult {\n +str error_message = None\n +ValidationResult fix_value = None\n }\n class FailResult {\n +str error_message\n +Any fix_value\n }\n ValidationResult <|-- PassResult\n ValidationResult <|-- FailResult\n```\n\n### OnFailAction Policies\n\nWhen validation fails, the `on_fail` parameter determines the behavior:\n\n| Policy | Behavior |\n|--------|----------|\n| `REASK` | Trigger a reask to the LLM |\n| `FIX` | Attempt to fix the value automatically |\n| `FILTER` | Remove invalid elements |\n| `REFRAIN` | Return empty/null value |\n| `NOOP` | Return the original value unchanged |\n| `EXCEPTION` | Raise an exception |\n\n资料来源：[guardrails/validator_service/validator_service_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_service/validator_service_base.py)\n\n## Validator Service\n\n### Sequential Validator Service\n\nThe `SequentialValidatorService` executes validators in order, one after another, stopping on the first failure unless configured otherwise.\n\nKey methods:\n\n| Method | Description |\n|--------|-------------|\n| `before_run_validator` | Prepares logging and tracking before validation |\n| `after_run_validator` | Records results and timing after validation |\n| `run_validator` | Executes a single validator's validation logic |\n\n资料来源：[guardrails/validator_service/validator_service_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_service/validator_service_base.py)\n\n### Validation Logging\n\nThe `ValidatorLogs` class tracks each validator execution:\n\n```python\nvalidator_logs = ValidatorLogs(\n validatorName=validator_class_name,\n valueBeforeValidation=value,\n registeredName=validator.rail_alias,\n propertyPath=absolute_property_path,\n instanceId=id(validator),\n)\n```\n\n| Field | Description |\n|-------|-------------|\n| `validatorName` | Class name of the validator |\n| `valueBeforeValidation` | Original value before validation |\n| `registeredName` | RAIL alias for the validator |\n| `propertyPath` | JSON path to the validated property |\n| `instanceId` | Memory address of validator instance |\n| `start_time` | Timestamp when validation began |\n| `end_time` | Timestamp when validation completed |\n| `validation_result` | Result of the validation |\n\n资料来源：[guardrails/validator_service/validator_service_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_service/validator_service_base.py)\n\n## Guard Integration\n\n### Attaching Validators to Guard\n\nValidators are attached to a `Guard` instance using the `.use()` method:\n\n```python\nguard = Guard().use(\n RegexMatch, regex=\"\\\\(?\\\\d{3}\\\\)?-? *\\\\d{3}-? *-?\\\\d{4}\"\n)\n```\n\nThe `use()` method signature:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `*validators` | Validator | Positional args for validators |\n| `on` | str | Property path (\"output\", \"messages\", \"$.property\") |\n\n```python\ndef use(\n self,\n *validators: Validator,\n on: str = \"output\",\n **kwargs,\n) -> \"Guard\":\n```\n\n资料来源：[guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n### Validation Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Guard\n participant ValidatorService\n participant Validator\n participant LLM\n\n User->>Guard: validate(llm_output)\n Guard->>Guard: parse(llm_output)\n Guard->>ValidatorService: run_validators()\n ValidatorService->>Validator: before_run_validator()\n Validator->>Validator: validate(value, metadata)\n Validator-->>ValidatorService: ValidationResult\n ValidatorService->>Validator: after_run_validator()\n ValidatorService-->>Guard: ValidationOutcome\n Guard-->>User: Pass/Fail with corrections\n```\n\n### Getting Attached Validators\n\nRetrieve validators attached to a specific property:\n\n```python\nvalidators = guard.get_validators(on=\"output\")\n```\n\n| Parameter | Valid Options | Description |\n|-----------|---------------|-------------|\n| `on` | `\"output\"`, `\"messages\"`, `\"$.path\"` | Property to query |\n\n资料来源：[guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n\n## Validation History Tracking\n\n### Call and Iteration Model\n\nValidation history is tracked through a hierarchical model:\n\n```mermaid\nclassDiagram\n class Call {\n +str id\n +Stack~Iteration~ iterations\n +CallInputs inputs\n +Exception exception\n }\n class Iteration {\n +Step[] steps\n +IterationOutputs outputs\n }\n class Step {\n +ValidatorLogs[] validator_logs\n }\n Call \"1\" --> \"*\" Iteration\n Iteration \"1\" --> \"*\" Step\n```\n\n| Class | Purpose |\n|-------|---------|\n| `Call` | Represents a single Guard execution (validate/parse/call) |\n| `Iteration` | A single validation round, including reasks |\n| `Step` | Contains validator execution logs |\n\n资料来源：[guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n\n### Call Inputs\n\nThe `CallInputs` class captures the original inputs to each Guard invocation:\n\n- `llm_output`: Raw LLM response\n- ` Prompt parameters and messages\n- Configuration options passed during validation\n\n## Telemetry and Tracing\n\n### Validator Tracing\n\nThe validator tracing system provides observability into validation execution:\n\n```mermaid\ngraph TD\n A[Validate Request] --> B[trace_validator_decorator]\n B --> C[Create Span]\n C --> D[Execute Validator]\n D --> E{Success?}\n E -->|Yes| F[Record PassResult]\n E -->|No| G[Record FailResult]\n F --> H[Add Attributes]\n G --> H\n H --> I[Close Span]\n I --> J[Return Result]\n```\n\nKey tracing attributes:\n\n| Attribute | Description |\n|-----------|-------------|\n| `validator_name` | Name of the validator class |\n| `validator_span` | OpenTelemetry span reference |\n| `obj_id` | Object identifier |\n| `on_fail_descriptor` | Policy applied on failure |\n| `init_kwargs` | Validator initialization arguments |\n| `validation_session_id` | Session identifier |\n\n资料来源：[guardrails/telemetry/validator_tracing.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/telemetry/validator_tracing.py)\n\n## Creating Custom Validators\n\n### Validator Template\n\nThe CLI command `guardrails create-validator` generates a template:\n\n```bash\nguardrails create-validator MyValidator\n```\n\nGenerated template structure:\n\n```python\nfrom guardrails import Validator\nfrom guardrails.properties import register_validator\nfrom guardrails.classes import ValidationResult\n\n@register_validator(name=\"my_validator\", fmt=\"native\")\nclass MyValidator(Validator):\n \"\"\"Validator description.\n \n Args:\n arg_1: Description of the argument.\n on_fail: Policy when validation fails.\n \"\"\"\n \n def __init__(\n self,\n arg_1: str,\n on_fail: Optional[Callable] = None,\n ):\n super().__init__(on_fail=on_fail, arg_1=arg_1)\n self._arg_1 = arg_1\n\n def validate(self, value: Any, metadata: Dict) -> ValidationResult:\n \"\"\"Validates the input value.\n \n Args:\n value: The value to validate.\n metadata: Additional context for validation.\n \"\"\"\n if value != \"pass\":\n return FailResult(\n error_message=\"Value must be 'pass'\",\n fix_value=\"fails\"\n )\n return PassResult()\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n### Validator Registration\n\nValidators are registered using the `@register_validator` decorator:\n\n| Parameter | Description |\n|-----------|-------------|\n| `name` | Unique identifier for the validator |\n| `fmt` | Format (\"native\" or \"raw\") |\n| `rail_alias` | RAIL XML alias |\n\n## Hub Installation\n\n### Installing Validators from Hub\n\nValidators can be installed from Guardrails Hub:\n\n```bash\nguardrails hub install hub://guardrails/regex_match\n```\n\nThe `install()` function:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `package_uri` | str | Hub package URI (e.g., `hub://guardrails/regex_match`) |\n| `quiet` | bool | Suppress output |\n| `upgrade` | bool | Force upgrade to latest |\n\n```python\n>>> RegexMatch = install(\"hub://guardrails/regex_match\").RegexMatch\n>>> RegexMatch = install(\"hub://guard://guardrails/regex_match~=1.4\").RegexMatch\n```\n\n资料来源：[guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n### Installation Process\n\n```mermaid\ngraph LR\n A[Install Request] --> B[Get Validator ID]\n B --> C[Fetch Manifest]\n C --> D[Download Dependencies]\n D --> E[Install via Pip]\n E --> F[Register Validator]\n```\n\n## Usage Examples\n\n### Basic String Validation\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(\n RegexMatch, \n regex=\"\\\\(?\\\\d{3}\\\\)?-? *\\\\d{3}-? *-?\\\\d{4}\",\n on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # Passes\n```\n\n### Multiple Validators\n\n```python\nfrom guardrails import Guard\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck([\"Apple\", \"Microsoft\"]),\n on_fail=OnFailAction.EXCEPTION\n).use(\n ToxicLanguage(threshold=0.5),\n on_fail=OnFailAction.FILTER\n)\n```\n\n### Custom Validator\n\n```python\nfrom guardrails import Validator\nfrom guardrails.classes import ValidationResult, PassResult, FailResult\n\nclass UppercaseValidator(Validator):\n def validate(self, value, metadata):\n if value.isupper():\n return PassResult()\n return FailResult(\n error_message=\"Value must be uppercase\",\n fix_value=value.upper()\n )\n\nguard = Guard().use(UppercaseValidator)\n```\n\n## Best Practices\n\n1. **Error Messages**: Provide clear, actionable error messages in `FailResult`\n2. **Fix Values**: Always provide sensible `fix_value` when possible\n3. **Metadata**: Use metadata for context-aware validation (e.g., schema info)\n4. **Ordering**: Place more restrictive validators first for early failure\n5. **Testing**: Test both passing and failing cases for each validator\n\n## Related Components\n\n| Component | File | Role |\n|-----------|------|------|\n| Guard | `guardrails/guard.py` | Main entry point for validation |\n| ValidatorService | `validator_service_base.py` | Orchestrates validation execution |\n| Call History | `classes/history/call.py` | Tracks validation execution history |\n| Hub Install | `hub/install.py` | Handles validator distribution |\n| Telemetry | `telemetry/validator_tracing.py` | Observability into validation |\n\n---\n\n\n\n## Schema Processing\n\n### 相关页面\n\n相关主题：[Guard Class Reference](#guard-class), [Execution Pipeline](#execution-pipeline)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n- [guardrails/schema/pydantic_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/pydantic_schema.py)\n- [guardrails/schema/primitive_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/primitive_schema.py)\n- [guardrails/schema/validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/validator.py)\n \n\n# Schema Processing\n\nSchema Processing is the core system within Guardrails that handles conversion, validation, and transformation of data structures between different schema formats. It provides the foundational infrastructure for validating LLM outputs against defined schemas, supporting multiple schema specification formats including RAIL (Rich AI Language), Pydantic models, and JSON Schema.\n\n## Overview\n\nThe Schema Processing module enables Guardrails to:\n\n- Convert JSON Schema to RAIL output specifications\n- Build element hierarchies from JSON Schema definitions\n- Support multiple data types including primitives, dates, times, and enums\n- Map validators to schema elements\n- Generate structured output from LLM responses\n\n资料来源：[guardrails/schema/rail_schema.py:1-50]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[JSON Schema / Pydantic / RAIL] --> B[Schema Processing Module]\n B --> C[rail_schema.py]\n B --> D[pydantic_schema.py]\n B --> E[primitive_schema.py]\n B --> F[validator.py]\n C --> G[build_element]\n C --> H[json_schema_to_rail_output]\n D --> I[Schema Generation]\n E --> J[Type Handling]\n F --> K[Validator Mapping]\n G --> L[XML Element Tree]\n H --> M[RAIL Output String]\n```\n\n## Core Components\n\n### Schema Type System\n\nThe schema processing system uses a dual type classification system:\n\n| Type Category | Values | Description |\n|---------------|--------|-------------|\n| **SimpleTypes** | STRING, INTEGER, NUMBER, BOOLEAN, ARRAY, OBJECT, NULL | JSON Schema primitive types |\n| **RailTypes** | STRING, INTEGER, FLOAT, BOOL, DATE, TIME, DATETIME, PERCENTAGE, ENUM | RAIL-specific type representations |\n\n资料来源：[guardrails/schema/rail_schema.py:30-45]()\n\n### Type Mapping Matrix\n\n```mermaid\ngraph LR\n A[JSON Schema Type] -->|Mapping| B[Internal Schema Type]\n A1[STRING] --> B1[SimpleTypes.STRING]\n A2[integer] --> A2a[integer] --> B2[SimpleTypes.INTEGER]\n A3[number] --> A3a[number] --> B3[SimpleTypes.NUMBER]\n A4[boolean] --> B4[SimpleTypes.BOOLEAN]\n A5[array] --> B5[SimpleTypes.ARRAY]\n A6[object] --> B6[SimpleTypes.OBJECT]\n```\n\n### build_element Function\n\nThe `build_element` function is the central dispatcher for converting JSON Schema definitions into XML element structures:\n\n```python\ndef build_element(\n json_schema: Dict[str, Any],\n validator_map: ValidatorMap,\n *,\n json_path: str = \"$\",\n elem: Callable[..., _Element] = SubElement,\n tag_override: Optional[str] = None,\n parent: Optional[_Element] = None,\n required: Optional[str] = \"true\",\n attributes: Optional[Dict[str, Any]] = None,\n) -> _Element:\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `json_schema` | Dict[str, Any] | required | The JSON Schema definition to process |\n| `validator_map` | ValidatorMap | required | Mapping of validator names to implementations |\n| `json_path` | str | \"$\" | Current path in the JSON structure for tracking |\n| `elem` | Callable | SubElement | Element construction function |\n| `tag_override` | Optional[str] | None | Override the XML tag name |\n| `parent` | Optional[_Element] | None | Parent element for nesting |\n| `required` | Optional[str] | \"true\" | Whether field is required |\n| `attributes` | Optional[Dict[str, Any]] | None | Additional XML attributes |\n\n资料来源：[guardrails/schema/rail_schema.py:100-130]()\n\n### json_schema_to_rail_output Function\n\nConverts a JSON Schema back to RAIL XML format for interoperability:\n\n```python\ndef json_schema_to_rail_output(\n json_schema: Dict[str, Any], validator_map: ValidatorMap\n) -> str:\n```\n\n**Process Flow:**\n\n```mermaid\ngraph TD\n A[JSON Schema Input] --> B[jsonref.replace_refs]\n B --> C[dereferenced_json_schema]\n C --> D[build_element with tag_override='output']\n D --> E[ET.tostring with pretty_print]\n E --> F[canonicalize output]\n F --> G[Replace
entities]\n G --> H[RAIL XML String]\n```\n\n资料来源：[guardrails/schema/rail_schema.py:60-75]()\n\n## Type-Specific Processing\n\n### String Element Builder\n\nThe `build_string_element` function handles all string-based types with special formatting:\n\n```mermaid\ngraph TD\n A[String Type Detected] --> B{format.internal_type}\n B -->|DATE| C[Set date-format attribute]\n B -->|TIME| D[Set time-format attribute]\n B -->|DATETIME| E[Set datetime-format attribute]\n B -->|PERCENTAGE| F[Set percentage handling]\n B -->|STRING| G[Standard string processing]\n C --> H[Return Element with attributes]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n**Date/Time Format Handling:**\n\n| Internal Type | XML Attribute | Purpose |\n|---------------|---------------|---------|\n| `RailTypes.DATE` | `date-format` | Custom date patterns |\n| `RailTypes.TIME` | `time-format` | Custom time patterns |\n| `RailTypes.DATETIME` | `datetime-format` | Custom datetime patterns |\n\n资料来源：[guardrails/schema/rail_schema.py:140-180]()\n\n### Format Extraction\n\nThe format extraction system maps JSON Schema formats to internal RAIL types:\n\n```python\ndef extract_format(\n element,\n internal_type: RailTypes,\n internal_format_attr: str,\n) -> Optional[Format]:\n```\n\n**Supported Format Mappings:**\n\n| JSON Schema Format | RailTypes Value | Internal Format Attr |\n|--------------------|-----------------|---------------------|\n| date | DATE | date-format |\n| date-time | DATETIME | datetime-format |\n| time | TIME | time-format |\n| percentage | PERCENTAGE | (empty string) |\n| email | STRING | - |\n| uri | STRING | - |\n| uuid | STRING | - |\n\n资料来源：[guardrails/schema/rail_schema.py:200-250]()\n\n## Integration with Guard Class\n\nThe Schema Processing module integrates with the Guard class through multiple factory methods:\n\n### Guard.for_pydantic\n\nCreates a Guard instance from a Pydantic BaseModel:\n\n```python\n@classmethod\ndef for_pydantic(\n cls,\n output_class: ModelOrListOfModels,\n *,\n reask_messages: Optional[List[Dict]] = None,\n messages: Optional[List[Dict]] = None,\n name: Optional[str] = None,\n description: Optional[str] = None,\n output_formatter: Optional[Union[str, BaseFormatter]] = None,\n):\n```\n\n资料来源：[guardrails/guard.py:150-180]()\n\n### Guard.for_rail\n\nCreates a Guard instance from a `.rail` file:\n\n```python\n@classmethod\ndef for_rail(\n cls,\n rail_file: str,\n *,\n name: Optional[str] = None,\n description: Optional[str] = None,\n):\n```\n\n资料来源：[guardrails/guard.py:200-230]()\n\n### Guard.for_rail_string\n\nCreates a Guard instance from a RAIL XML string:\n\n```python\n@classmethod\ndef for_rail_string(\n cls,\n rail_string: str,\n *,\n name: Optional[str] = None,\n description: Optional[str] = None,\n):\n```\n\n资料来源：[guardrails/guard.py:240-270]()\n\n## Data Flow Diagram\n\n```mermaid\nsequenceDiagram\n participant User\n participant Guard\n participant SchemaProcessor\n participant ValidatorMap\n participant LLM\n \n User->>Guard: for_pydantic(PetModel)\n Guard->>SchemaProcessor: Convert Pydantic to JSON Schema\n SchemaProcessor->>SchemaProcessor: build_element for each field\n SchemaProcessor->>ValidatorMap: Map validators\n Guard->>LLM: Prompt with schema hints\n LLM->>Guard: Raw output\n Guard->>SchemaProcessor: validate(output)\n SchemaProcessor->>ValidatorMap: Run validators\n ValidatorMap-->>SchemaProcessor: Validation result\n SchemaProcessor-->>Guard: Structured result\n Guard-->>User: GuardResponse\n```\n\n## Schema to RAIL Conversion Rules\n\n### Type Conversions\n\n| JSON Schema | RAIL Element | Notes |\n|-------------|--------------|-------|\n| `{type: string}` | `` | Default string type |\n| `{type: integer}` | `` | Whole numbers only |\n| `{type: number}` | `` | Floating point |\n| `{type: boolean}` | `` | True/false values |\n| `{type: array}` | `` | Array of items |\n| `{type: object}` | `