google styled doc

mail_intake/models/__init__.py

@@ -1,6 +1,10 @@
 """
 Domain models for Mail Intake.
 
+---
+
+## Summary
+
 This package defines the **canonical, provider-agnostic data models**
 used throughout the Mail Intake ingestion pipeline.
 
@@ -11,6 +15,15 @@ Models in this package:
 - Serve as stable inputs for downstream processing and analysis
 
 These models form the core internal data contract of the library.
+
+---
+
+## Public API
+
+    MailIntakeMessage
+    MailIntakeThread
+
+---
 """
 
 from .message import MailIntakeMessage

mail_intake/models/message.py

@@ -1,6 +1,10 @@
 """
 Message domain models for Mail Intake.
 
+---
+
+## Summary
+
 This module defines the **canonical, provider-agnostic representation**
 of an individual email message as used internally by the Mail Intake
 ingestion pipeline.
@@ -19,37 +23,58 @@ class MailIntakeMessage:
     """
     Canonical internal representation of a single email message.
 
-    This model represents a fully parsed and normalized email message.
-    It is intentionally provider-agnostic and suitable for persistence,
-    indexing, and downstream processing.
+    Notes:
+        **Guarantees:**
 
-    No provider-specific identifiers, payloads, or API semantics
-    should appear in this model.
+            - This model represents a fully parsed and normalized email message
+            - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing
+
+        **Constraints:**
+        
+            - No provider-specific identifiers, payloads, or API semantics should appear in this model
     """
 
     message_id: str
-    """Provider-specific message identifier."""
+    """
+    Provider-specific message identifier.
+    """
 
     thread_id: str
-    """Provider-specific thread identifier to which this message belongs."""
+    """
+    Provider-specific thread identifier to which this message belongs.
+    """
 
     timestamp: datetime
-    """Message timestamp as a timezone-naive UTC datetime."""
+    """
+    Message timestamp as a timezone-naive UTC datetime.
+    """
 
     from_email: str
-    """Sender email address."""
+    """
+    Sender email address.
+    """
 
     from_name: Optional[str]
-    """Optional human-readable sender name."""
+    """
+    Optional human-readable sender name.
+    """
 
     subject: str
-    """Raw subject line of the message."""
+    """
+    Raw subject line of the message.
+    """
 
     body_text: str
-    """Extracted plain-text body content of the message."""
+    """
+    Extracted plain-text body content of the message.
+    """
 
     snippet: str
-    """Short provider-supplied preview snippet of the message."""
+    """
+    Short provider-supplied preview snippet of the message.
+    """
 
     raw_headers: Dict[str, str]
-    """Normalized mapping of message headers (header name → value)."""
+    """
+    Normalized mapping of message headers (header name → value).
+    """

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)