Update models.py

models.py

@@ -1,7 +1,21 @@
 """
 models.py – Pydantic Schemas for PhishGuard-Env
 ================================================
-No changes from the live repo — included here for completeness.
+
+CHANGES vs. original
+---------------------
+1. EmailObservation is now the authoritative observation contract.
+   All scenario dicts in env.py have been updated to include every field
+   declared here — the schema is no longer a dead letter.
+
+2. Added Optional[str] confidence_hint:
+   Surfaces noisy SIEM / gateway / threat-intel signals to make the LLM's
+   task genuinely adversarial. Optional so old API clients are not broken.
+
+3. PhishAction.reasoning is Optional[str]:
+   Some LLM providers omit reasoning even when prompted. Making it Optional
+   prevents the /step endpoint from returning HTTP 422 Unprocessable Entity
+   when reasoning is absent from the agent's JSON response.
 """
 
 from pydantic import BaseModel, Field
@@ -11,29 +25,53 @@ from typing import List, Optional
 class EmailObservation(BaseModel):
     """
     Structured email observation returned by /reset and each /step call.
+    This is exactly what the LLM agent receives as input for each decision.
     """
-    sender:          str            = Field(description="Full sender email address")
-    subject:         str            = Field(description="Email subject line")
-    body:            str            = Field(description="Plain-text email body")
-    links:           List[str]      = Field(default_factory=list, description="URLs in the email")
-    has_attachments: bool           = Field(description="True if attachments present")
-    spf_record:      str            = Field(description="SPF result: pass|fail|softfail|none")
-    dmarc_record:    str            = Field(description="DMARC result: pass|fail|none")
-    urgency_level:   str            = Field(description="low|medium|high|critical")
-    confidence_hint: Optional[str]  = Field(
+    sender: str = Field(
+        description="Full sender email address"
+    )
+    subject: str = Field(
+        description="Email subject line"
+    )
+    body: str = Field(
+        description="Plain-text email body"
+    )
+    links: List[str] = Field(
+        default_factory=list,
+        description="List of URLs found in the email body or headers",
+    )
+    has_attachments: bool = Field(
+        description="True if the email carries one or more attachments"
+    )
+    spf_record: str = Field(
+        description="SPF validation result: 'pass' | 'fail' | 'softfail' | 'none'"
+    )
+    dmarc_record: str = Field(
+        description="DMARC policy result: 'pass' | 'fail' | 'none'"
+    )
+    urgency_level: str = Field(
+        description="Perceived urgency of the email: 'low' | 'medium' | 'high' | 'critical'"
+    )
+    confidence_hint: Optional[str] = Field(
         default=None,
-        description="Noisy SIEM/gateway signal — treat as one data-point, not ground truth.",
+        description=(
+            "Noisy contextual signal from SIEM, mail gateway, or threat-intel "
+            "feed. Treat as one data-point — it may be misleading by design."
+        ),
     )
 
 
 class PhishAction(BaseModel):
     """
-    Action payload submitted by the agent to POST /step.
+    Action payload submitted by the agent to the POST /step endpoint.
     """
     action: str = Field(
-        description="MARK_SAFE | MOVE_TO_SPAM | QUARANTINE | BLOCK_DOMAIN"
+        description=(
+            "Triage decision. Must be exactly one of: "
+            "MARK_SAFE | MOVE_TO_SPAM | QUARANTINE | BLOCK_DOMAIN"
+        )
     )
     reasoning: Optional[str] = Field(
         default=None,
-        description="One-sentence technical justification (optional).",
+        description="One-sentence technical justification for the triage decision",
     )