>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3582367. --> Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !1384 >>> <p>[Tracker]<br> <strong>Update Summary: </strong>[One-line status update for stakeholders]<br> <strong>Short Description: </strong>Add documentation for the Guardrails system<br> <strong>Check-in Date: </strong>MM/DD/YYYY<br> [/Tracker]</p> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Guardrails system is a significant feature of the AI module that allows developers and site builders to add safety and validation checks on AI inputs and outputs. Despite having a full plugin system with config entities, result types, and streaming support, there is no documentation for it at all.</p> <p>The system includes:</p> <ul> <li><code>AiGuardrail</code> and <code>AiGuardrailSet</code> config entities for managing guardrails through the UI</li> <li><code>AiGuardrailPluginManager</code> for discovering and loading guardrail plugins</li> <li><code>AiGuardrailInterface</code> with <code>processInput()</code> and <code>processOutput()</code> methods</li> <li>Four result types: <code>PassResult</code>, <code>StopResult</code>, <code>RewriteInputResult</code>, <code>RewriteOutputResult</code></li> <li>Special interfaces: <code>NonStreamableGuardrailInterface</code> and <code>NonDeterministicGuardrailInterface</code></li> <li>Score aggregation with configurable stop thresholds on guardrail sets</li> <li>Two built-in guardrail plugins: <code>RegexpGuardrail</code> and <code>RestrictToTopic</code></li> <li>Permissions: <code>administer guardrails</code> and <code>administer guardrail sets</code></li> </ul> <p>Without documentation, developers cannot write custom guardrail plugins and site builders do not know how to configure and use guardrails to protect their AI-powered features.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ul> <li>Create a developer documentation page under <code>docs/developers/guardrails.md</code> explaining the guardrails architecture, how to write a custom guardrail plugin, the available result types, and how pre/post-generation guardrails work.</li> <li>Include a code example showing a minimal custom guardrail plugin implementing <code>AiGuardrailInterface</code>.</li> <li>Document the <code>NonStreamableGuardrailInterface</code> marker and when to use it (guardrails that need the full response, not streaming chunks).</li> <li>Document the <code>NonDeterministicGuardrailInterface</code> for guardrails that call AI services themselves.</li> <li>Document the score aggregation mechanism and stop threshold on <code>AiGuardrailSet</code>.</li> <li>Document how to attach a guardrail set to an AI input using <code>AiGuardrailHelper::applyGuardrailSetToChatInput()</code>.</li> <li>Add the new page to the <code>mkdocs.yml</code> nav under the Develop section.</li> </ul> <h3 id="summary-ai-usage">AI usage (if applicable)</h3> <p>[x] AI Assisted Issue<br> This issue was generated with AI assistance, but was reviewed and refined by the creator.</p> <p>[ ] AI Assisted Code<br> [ ] AI Generated Code<br> [ ] Vibe Coded</p> <p>- <strong>This issue was created with the help of AI</strong></p>