google styled doc

mail_intake/models/thread.py

@@ -1,6 +1,10 @@
 """
 Thread domain models for Mail Intake.
 
+---
+
+## Summary
+
 This module defines the **canonical, provider-agnostic representation**
 of an email thread as used internally by the Mail Intake ingestion pipeline.
 
@@ -20,40 +24,53 @@ class MailIntakeThread:
     """
     Canonical internal representation of an email thread.
 
-    A thread groups multiple related messages under a single subject
-    and participant set. It is designed to support reasoning over
-    conversational context such as job applications, interviews,
-    follow-ups, and ongoing discussions.
+    Notes:
+        **Guarantees:**
 
-    This model is provider-agnostic and safe to persist.
+            - A thread groups multiple related messages under a single subject and participant set
+            - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions
+            - This model is provider-agnostic and safe to persist
     """
 
     thread_id: str
-    """Provider-specific thread identifier."""
+    """
+    Provider-specific thread identifier.
+    """
 
     normalized_subject: str
-    """Normalized subject line used to group related messages."""
+    """
+    Normalized subject line used to group related messages.
+    """
 
     participants: Set[str] = field(default_factory=set)
-    """Set of unique participant email addresses observed in the thread."""
+    """
+    Set of unique participant email addresses observed in the thread.
+    """
 
     messages: List[MailIntakeMessage] = field(default_factory=list)
-    """Ordered list of messages belonging to this thread."""
+    """
+    Ordered list of messages belonging to this thread.
+    """
 
     last_activity_at: datetime | None = None
-    """Timestamp of the most recent message in the thread."""
+    """
+    Timestamp of the most recent message in the thread.
+    """
 
     def add_message(self, message: MailIntakeMessage) -> None:
         """
         Add a message to the thread and update derived fields.
 
-        This method:
-        - Appends the message to the thread
-        - Tracks unique participants
-        - Updates the last activity timestamp
-
         Args:
-            message: Parsed mail message to add to the thread.
+            message (MailIntakeMessage):
+                Parsed mail message to add to the thread.
+
+        Notes:
+            **Responsibilities:**
+
+                - Appends the message to the thread
+                - Tracks unique participants
+                - Updates the last activity timestamp
         """
         self.messages.append(message)