lib init

mail_intake/models/message.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional, Dict
+
+
+@dataclass(frozen=True)
+class MailIntakeMessage:
+    """
+    Canonical internal representation of a single email message.
+
+    This model is provider-agnostic and safe to persist.
+    No Gmail-specific fields should appear here.
+    """
+
+    message_id: str
+    thread_id: str
+    timestamp: datetime
+
+    from_email: str
+    from_name: Optional[str]
+
+    subject: str
+    body_text: str
+    snippet: str
+
+    raw_headers: Dict[str, str]

mail_intake/models/thread.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List, Set
+
+from mail_intake.models.message import MailIntakeMessage
+
+
+@dataclass
+class MailIntakeThread:
+    """
+    Canonical internal representation of an email thread.
+
+    Threads are the primary unit of reasoning for correspondence
+    workflows (job applications, interviews, follow-ups, etc.).
+    """
+
+    thread_id: str
+    normalized_subject: str
+
+    participants: Set[str] = field(default_factory=set)
+    messages: List[MailIntakeMessage] = field(default_factory=list)
+
+    last_activity_at: datetime | None = None
+
+    def add_message(self, message: MailIntakeMessage) -> None:
+        """
+        Add a message to the thread and update derived fields.
+        """
+        self.messages.append(message)
+
+        if message.from_email:
+            self.participants.add(message.from_email)
+
+        if self.last_activity_at is None or message.timestamp > self.last_activity_at:
+            self.last_activity_at = message.timestamp