[doc] update baml example instruction on user roles

docs/docs/examples/examples/patient_form_extraction_baml.md

@@ -142,6 +142,7 @@ function ExtractPatientInfo(intake_form: pdf) -> Patient {
     Extract all patient information from the following intake form document.
     Please be thorough and extract all available information accurately.
 
+    {{ _.role("user") }}
     {{ intake_form }}
 
     Fill in with "N/A" for required fields if the information is not available.
@@ -153,6 +154,21 @@ function ExtractPatientInfo(intake_form: pdf) -> Patient {
 
 We specify `client Gemini` and a prompt template. The special variable `{{ intake_form }}` injects the PDF, and `{{ ctx.output_format }}` tells BAML to expect the structured format defined by the return type. The prompt explicitly asks Gemini to extract all fields, filling “N/A” if missing.
 
+:::tip Why `role("user")` Matters in BAML Extraction
+
+In our BAML example above, there's a subtle but **crucial line**: `{{ _.role("user") }}` is added at the start of the prompt.
+
+> This ensures the **PDF content is explicitly included as part of the user message**, rather than the system prompt.
+
+**Why does this matter?**  
+- For Gemini and Anthropic models, BAML can sometimes infer or adjust the prompt structure, so extraction works either way.
+- For **OpenAI models** (e.g., GPT-4/GPT-4o), if the PDF is **not** in the user role, the model doesn't see the file content — so extractions will fail or return empty fields.
+- This can easily trip you up.If you're using BAML, **always double-check your prompt roles when adding file inputs**—especially for OpenAI backends.
+
+:::
+
+
+
 ## Configure the LLM client to use Google’s Gemini model
 
 ```python