>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3582366. --> Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !1380 >>> <p>[Tracker]<br> <strong>Update Summary: </strong>[One-line status update for stakeholders]<br> <strong>Short Description: </strong>Add documentation for PromptJsonDecoder and PromptCodeBlockExtractor services<br> <strong>Check-in Date: </strong>MM/DD/YYYY<br> [/Tracker]</p> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The AI module provides two helper services for extracting structured content from AI responses, and neither has documentation:</p> <p>The <code>ai.prompt_json_decode</code> service (<code>src/Service/PromptJsonDecoder/PromptJsonDecoder.php</code>) decodes JSON from AI chat messages. It handles both regular and streaming responses, automatically detects JSON in the response, and supports extraction from code blocks. This is essential when using AI to generate structured data (e.g. automators, structured output).</p> <p>The <code>ai.prompt_code_block_extractor</code> service (<code>src/Service/PromptCodeBlockExtractor/PromptCodeBlockExtractor.php</code>) extracts code blocks from AI responses. It supports multiple code block types (HTML, Twig, YAML, JSON, CSS) and works with both regular and streaming responses. This is used when the AI generates code that needs to be extracted from the surrounding markdown.</p> <p>Both services follow the same pattern - accepting either a <code>ChatMessage</code> or <code>StreamedChatMessageIteratorInterface</code> and returning the extracted content. They are commonly used together when processing AI output.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ul> <li>Create a single documentation page at <code>docs/developers/response_helpers.md</code> (or similar) covering both services.</li> <li>Document the <code>PromptJsonDecoder::decode()</code> method, its parameters, and how it auto-detects JSON in AI responses.</li> <li>Document the <code>PromptCodeBlockExtractor::extract()</code> method, its supported code block types (html, twig, yaml, json, css), and how to specify which type to extract.</li> <li>Show usage examples for both services with regular and streaming responses.</li> <li>Add the new page to the <code>mkdocs.yml</code> nav under the Develop section (e.g. under Helper Services).</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>