fix: validate moderation endpoint response format and document contract

Log a warning with a link to the OpenAI moderations docs when the
endpoint returns an unexpected format. Document the expected request
and response shape in the config field description.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Sébastien Han <seb@redhat.com>

Author: leseb

docs/docs/providers/responses/inline_builtin.mdx

@@ -93,7 +93,7 @@ Be concise, structured, and focused on helping the next LLM seamlessly continue
 | `compaction_config.summarization_model` | `str \| None` | No |  | Model to use for generating compaction summaries. If not set, uses the same model as the conversation. |
 | `compaction_config.default_compact_threshold` | `int \| None` | No |  | Default token threshold for auto-compaction via context_management. If set, conversations exceeding this token count will be automatically compacted. |
 | `compaction_config.tokenizer_encoding` | `str \| None` | No |  | Tiktoken encoding name for token counting (e.g. 'o200k_base', 'cl100k_base'). If not set, the encoding is resolved from the model name via tiktoken.encoding_for_model(). |
-| `moderation_endpoint` | `str \| None` | No |  | URL of an OpenAI-compatible /v1/moderations endpoint for guardrails. |
+| `moderation_endpoint` | `str \| None` | No |  | URL of an OpenAI-compatible /v1/moderations endpoint for guardrails. The endpoint must accept POST {"input": "text"} and return {"results": [{"flagged": bool, "categories": {...}}]}. |
 
 ## Sample Configuration
 

src/ogx/providers/inline/responses/builtin/config.py

@@ -80,7 +80,9 @@ class BuiltinResponsesImplConfig(BaseModel):
 
     moderation_endpoint: str | None = Field(
         default=None,
-        description="URL of an OpenAI-compatible /v1/moderations endpoint for guardrails.",
+        description="URL of an OpenAI-compatible /v1/moderations endpoint for guardrails. "
+        'The endpoint must accept POST {"input": "text"} and return '
+        '{"results": [{"flagged": bool, "categories": {...}}]}.',
     )
 
     @classmethod

src/ogx/providers/inline/responses/builtin/responses/utils.py

@@ -548,7 +548,11 @@ async def run_guardrails(
     moderation_endpoint: str | None,
     messages: str,
 ) -> str | None:
-    """Run content moderation by calling an external OpenAI-compatible moderation endpoint."""
+    """Run content moderation by calling an external OpenAI-compatible moderation endpoint.
+
+    The endpoint must conform to the OpenAI Moderations API response format:
+    {"id": "...", "model": "...", "results": [{"flagged": bool, "categories": {...}, ...}]}
+    """
     if not messages or not moderation_endpoint:
         return None
 
@@ -562,7 +566,20 @@ async def run_guardrails(
             logger.warning("Failed to call moderation endpoint", endpoint=moderation_endpoint)
             return None
 
-    for result in resp.json().get("results", []):
+    data = resp.json()
+    results = data.get("results")
+    if not isinstance(results, list):
+        logger.warning(
+            "Moderation endpoint returned unexpected format (expected OpenAI-compatible "
+            "response with 'results' array, see https://platform.openai.com/docs/api-reference/moderations)",
+            endpoint=moderation_endpoint,
+            response_keys=list(data.keys()) if isinstance(data, dict) else type(data).__name__,
+        )
+        return None
+
+    for result in results:
+        if not isinstance(result, dict):
+            continue
         if result.get("flagged", False):
             categories = result.get("categories", {})
             flagged_cats = [c for c, f in categories.items() if f]