Merge branch 'feature/issue-309-openai-structured-schema-blocks'

fix(#309): OpenAI strict schema for email insight blocks (distinct anyOf first keys, test, richer API error logs).

Author: mottych

coaching/src/infrastructure/llm/openai_provider.py

@@ -289,7 +289,14 @@ async def generate(
             )
 
         except Exception as e:
-            logger.error("OpenAI Responses API call failed", error=str(e), model=model)
+            err_body = getattr(e, "body", None)
+            logger.error(
+                "OpenAI Responses API call failed",
+                error=str(e),
+                model=model,
+                has_response_schema=response_schema is not None,
+                error_body=err_body,
+            )
             raise RuntimeError(f"OpenAI API call failed: {e}") from e
 
     async def generate_stream(

coaching/src/models/responses.py

@@ -263,36 +263,40 @@ class EmailInsightParagraphBlock(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    type: Literal["paragraph"] = "paragraph"
+    # Field order matters for OpenAI strict structured outputs: each branch of the
+    # blocks union is sent as anyOf; the API rejects anyOf object variants whose
+    # first property key is identical ("Objects provided via 'anyOf' must not
+    # share identical first keys"). Discriminator stays ``type`` but is not first.
     text: str = Field(min_length=1, max_length=600, description="Paragraph content")
+    type: Literal["paragraph"] = "paragraph"
 
 
 class EmailInsightListBlock(BaseModel):
     """List block in email insight payload."""
 
     model_config = ConfigDict(extra="forbid")
 
-    type: Literal["list"] = "list"
     items: list[str] = Field(
         min_length=1,
         max_length=6,
         description="List items for actionable guidance",
     )
+    type: Literal["list"] = "list"
 
 
 class EmailInsightCtaBlock(BaseModel):
     """CTA block in email insight payload."""
 
     model_config = ConfigDict(extra="forbid")
 
-    type: Literal["cta"] = "cta"
     label: str = Field(min_length=1, max_length=80, description="CTA label text")
     action: str = Field(min_length=1, max_length=120, description="CTA action identifier")
     url: str | None = Field(
         default=None,
         max_length=500,
         description="Optional URI link; https-only enforcement is handled by backend runtime policy",
     )
+    type: Literal["cta"] = "cta"
 
 
 EmailInsightBlock = Annotated[

coaching/tests/unit/application/ai_engine/test_llm_json_schema_adaptation.py

@@ -57,3 +57,41 @@ def test_unified_engine_adapt_routes_by_provider() -> None:
 
 def test_adapt_none_returns_none() -> None:
     assert UnifiedAIEngine._adapt_structured_schema_for_llm_provider(None, "openai") is None
+
+
+def _first_property_key_of_object_schema(obj: dict) -> str | None:
+    props = obj.get("properties")
+    if not isinstance(props, dict) or not props:
+        return None
+    return next(iter(props.keys()))
+
+
+def test_openai_blocks_anyof_branches_have_distinct_first_keys() -> None:
+    """OpenAI rejects anyOf when each object branch shares the same first key."""
+    full = EmailInsightResponse.model_json_schema(by_alias=True)
+    prepared = _prepare_like_engine(full, "EmailInsightResponse")
+    adapted = adapt_json_schema_for_openai_structured_output(prepared)
+
+    blocks = adapted.get("properties", {}).get("blocks")
+    assert isinstance(blocks, dict)
+    items = blocks.get("items")
+    assert isinstance(items, dict)
+    variants = items.get("anyOf") or items.get("oneOf")
+    assert isinstance(variants, list) and len(variants) == 3
+
+    first_keys: list[str] = []
+    for branch in variants:
+        assert isinstance(branch, dict)
+        if "$ref" in branch:
+            ref = branch["$ref"]
+            assert ref.startswith("#/$defs/")
+            def_name = ref.removeprefix("#/$defs/")
+            defn = adapted.get("$defs", {}).get(def_name)
+            assert isinstance(defn, dict)
+            key = _first_property_key_of_object_schema(defn)
+        else:
+            key = _first_property_key_of_object_schema(branch)
+        assert key is not None
+        first_keys.append(key)
+
+    assert len(set(first_keys)) == len(first_keys), f"duplicate first keys: {first_keys}"