docs/mcp/mail-intake/modules/mail_intake.models.thread.json

{
  "module": "mail_intake.models.thread",
  "content": {
    "path": "mail_intake.models.thread",
    "docstring": "# Summary\n\nThread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
    "objects": {
      "MailIntakeMessage": {
        "name": "MailIntakeMessage",
        "kind": "class",
        "path": "mail_intake.models.thread.MailIntakeMessage",
        "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])",
        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
        "members": {
          "message_id": {
            "name": "message_id",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.message_id",
            "signature": null,
            "docstring": "Provider-specific message identifier."
          },
          "thread_id": {
            "name": "thread_id",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.thread_id",
            "signature": null,
            "docstring": "Provider-specific thread identifier to which this message belongs."
          },
          "timestamp": {
            "name": "timestamp",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.timestamp",
            "signature": null,
            "docstring": "Message timestamp as a timezone-naive UTC datetime."
          },
          "from_email": {
            "name": "from_email",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.from_email",
            "signature": null,
            "docstring": "Sender email address."
          },
          "from_name": {
            "name": "from_name",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.from_name",
            "signature": null,
            "docstring": "Optional human-readable sender name."
          },
          "subject": {
            "name": "subject",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.subject",
            "signature": null,
            "docstring": "Raw subject line of the message."
          },
          "body_text": {
            "name": "body_text",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.body_text",
            "signature": null,
            "docstring": "Extracted plain-text body content of the message."
          },
          "snippet": {
            "name": "snippet",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.snippet",
            "signature": null,
            "docstring": "Short provider-supplied preview snippet of the message."
          },
          "raw_headers": {
            "name": "raw_headers",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeMessage.raw_headers",
            "signature": null,
            "docstring": "Normalized mapping of message headers (header name → value)."
          }
        }
      },
      "MailIntakeThread": {
        "name": "MailIntakeThread",
        "kind": "class",
        "path": "mail_intake.models.thread.MailIntakeThread",
        "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)",
        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
        "members": {
          "thread_id": {
            "name": "thread_id",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeThread.thread_id",
            "signature": null,
            "docstring": "Provider-specific thread identifier."
          },
          "normalized_subject": {
            "name": "normalized_subject",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeThread.normalized_subject",
            "signature": null,
            "docstring": "Normalized subject line used to group related messages."
          },
          "participants": {
            "name": "participants",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeThread.participants",
            "signature": null,
            "docstring": "Set of unique participant email addresses observed in the thread."
          },
          "messages": {
            "name": "messages",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeThread.messages",
            "signature": null,
            "docstring": "Ordered list of messages belonging to this thread."
          },
          "last_activity_at": {
            "name": "last_activity_at",
            "kind": "attribute",
            "path": "mail_intake.models.thread.MailIntakeThread.last_activity_at",
            "signature": null,
            "docstring": "Timestamp of the most recent message in the thread."
          },
          "add_message": {
            "name": "add_message",
            "kind": "function",
            "path": "mail_intake.models.thread.MailIntakeThread.add_message",
            "signature": "add_message(message: MailIntakeMessage) -> None",
            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
          }
        }
      }
    }
  }
}