docs-and-mcps (#1)

Reviewed-on: #1
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

mcp_docs/modules/mail_intake.models.json

@@ -0,0 +1,415 @@
+{
+  "module": "mail_intake.models",
+  "content": {
+    "path": "mail_intake.models",
+    "docstring": "Domain models for Mail Intake.\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n- Represent fully parsed and normalized mail data\n- Are safe to persist, serialize, and index\n- Contain no provider-specific payloads or API semantics\n- Serve as stable inputs for downstream processing and analysis\n\nThese models form the core internal data contract of the library.",
+    "objects": {
+      "MailIntakeMessage": {
+        "name": "MailIntakeMessage",
+        "kind": "class",
+        "path": "mail_intake.models.MailIntakeMessage",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
+        "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.",
+        "members": {
+          "message_id": {
+            "name": "message_id",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.message_id",
+            "signature": "<bound method Alias.signature of Alias('message_id', 'mail_intake.models.message.MailIntakeMessage.message_id')>",
+            "docstring": "Provider-specific message identifier."
+          },
+          "thread_id": {
+            "name": "thread_id",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.thread_id",
+            "signature": "<bound method Alias.signature of Alias('thread_id', 'mail_intake.models.message.MailIntakeMessage.thread_id')>",
+            "docstring": "Provider-specific thread identifier to which this message belongs."
+          },
+          "timestamp": {
+            "name": "timestamp",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.timestamp",
+            "signature": "<bound method Alias.signature of Alias('timestamp', 'mail_intake.models.message.MailIntakeMessage.timestamp')>",
+            "docstring": "Message timestamp as a timezone-naive UTC datetime."
+          },
+          "from_email": {
+            "name": "from_email",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.from_email",
+            "signature": "<bound method Alias.signature of Alias('from_email', 'mail_intake.models.message.MailIntakeMessage.from_email')>",
+            "docstring": "Sender email address."
+          },
+          "from_name": {
+            "name": "from_name",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.from_name",
+            "signature": "<bound method Alias.signature of Alias('from_name', 'mail_intake.models.message.MailIntakeMessage.from_name')>",
+            "docstring": "Optional human-readable sender name."
+          },
+          "subject": {
+            "name": "subject",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.subject",
+            "signature": "<bound method Alias.signature of Alias('subject', 'mail_intake.models.message.MailIntakeMessage.subject')>",
+            "docstring": "Raw subject line of the message."
+          },
+          "body_text": {
+            "name": "body_text",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.body_text",
+            "signature": "<bound method Alias.signature of Alias('body_text', 'mail_intake.models.message.MailIntakeMessage.body_text')>",
+            "docstring": "Extracted plain-text body content of the message."
+          },
+          "snippet": {
+            "name": "snippet",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.snippet",
+            "signature": "<bound method Alias.signature of Alias('snippet', 'mail_intake.models.message.MailIntakeMessage.snippet')>",
+            "docstring": "Short provider-supplied preview snippet of the message."
+          },
+          "raw_headers": {
+            "name": "raw_headers",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeMessage.raw_headers",
+            "signature": "<bound method Alias.signature of Alias('raw_headers', 'mail_intake.models.message.MailIntakeMessage.raw_headers')>",
+            "docstring": "Normalized mapping of message headers (header name → value)."
+          }
+        }
+      },
+      "MailIntakeThread": {
+        "name": "MailIntakeThread",
+        "kind": "class",
+        "path": "mail_intake.models.MailIntakeThread",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
+        "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.",
+        "members": {
+          "thread_id": {
+            "name": "thread_id",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeThread.thread_id",
+            "signature": "<bound method Alias.signature of Alias('thread_id', 'mail_intake.models.thread.MailIntakeThread.thread_id')>",
+            "docstring": "Provider-specific thread identifier."
+          },
+          "normalized_subject": {
+            "name": "normalized_subject",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeThread.normalized_subject",
+            "signature": "<bound method Alias.signature of Alias('normalized_subject', 'mail_intake.models.thread.MailIntakeThread.normalized_subject')>",
+            "docstring": "Normalized subject line used to group related messages."
+          },
+          "participants": {
+            "name": "participants",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeThread.participants",
+            "signature": "<bound method Alias.signature of Alias('participants', 'mail_intake.models.thread.MailIntakeThread.participants')>",
+            "docstring": "Set of unique participant email addresses observed in the thread."
+          },
+          "messages": {
+            "name": "messages",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeThread.messages",
+            "signature": "<bound method Alias.signature of Alias('messages', 'mail_intake.models.thread.MailIntakeThread.messages')>",
+            "docstring": "Ordered list of messages belonging to this thread."
+          },
+          "last_activity_at": {
+            "name": "last_activity_at",
+            "kind": "attribute",
+            "path": "mail_intake.models.MailIntakeThread.last_activity_at",
+            "signature": "<bound method Alias.signature of Alias('last_activity_at', 'mail_intake.models.thread.MailIntakeThread.last_activity_at')>",
+            "docstring": "Timestamp of the most recent message in the thread."
+          },
+          "add_message": {
+            "name": "add_message",
+            "kind": "function",
+            "path": "mail_intake.models.MailIntakeThread.add_message",
+            "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
+            "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n    message: Parsed mail message to add to the thread."
+          }
+        }
+      },
+      "message": {
+        "name": "message",
+        "kind": "module",
+        "path": "mail_intake.models.message",
+        "signature": null,
+        "docstring": "Message domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
+        "members": {
+          "dataclass": {
+            "name": "dataclass",
+            "kind": "alias",
+            "path": "mail_intake.models.message.dataclass",
+            "signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
+            "docstring": null
+          },
+          "datetime": {
+            "name": "datetime",
+            "kind": "alias",
+            "path": "mail_intake.models.message.datetime",
+            "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
+            "docstring": null
+          },
+          "Optional": {
+            "name": "Optional",
+            "kind": "alias",
+            "path": "mail_intake.models.message.Optional",
+            "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
+            "docstring": null
+          },
+          "Dict": {
+            "name": "Dict",
+            "kind": "alias",
+            "path": "mail_intake.models.message.Dict",
+            "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
+            "docstring": null
+          },
+          "MailIntakeMessage": {
+            "name": "MailIntakeMessage",
+            "kind": "class",
+            "path": "mail_intake.models.message.MailIntakeMessage",
+            "signature": "<bound method Class.signature of Class('MailIntakeMessage', 17, 55)>",
+            "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.",
+            "members": {
+              "message_id": {
+                "name": "message_id",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.message_id",
+                "signature": null,
+                "docstring": "Provider-specific message identifier."
+              },
+              "thread_id": {
+                "name": "thread_id",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.thread_id",
+                "signature": null,
+                "docstring": "Provider-specific thread identifier to which this message belongs."
+              },
+              "timestamp": {
+                "name": "timestamp",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.timestamp",
+                "signature": null,
+                "docstring": "Message timestamp as a timezone-naive UTC datetime."
+              },
+              "from_email": {
+                "name": "from_email",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.from_email",
+                "signature": null,
+                "docstring": "Sender email address."
+              },
+              "from_name": {
+                "name": "from_name",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.from_name",
+                "signature": null,
+                "docstring": "Optional human-readable sender name."
+              },
+              "subject": {
+                "name": "subject",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.subject",
+                "signature": null,
+                "docstring": "Raw subject line of the message."
+              },
+              "body_text": {
+                "name": "body_text",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.body_text",
+                "signature": null,
+                "docstring": "Extracted plain-text body content of the message."
+              },
+              "snippet": {
+                "name": "snippet",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.snippet",
+                "signature": null,
+                "docstring": "Short provider-supplied preview snippet of the message."
+              },
+              "raw_headers": {
+                "name": "raw_headers",
+                "kind": "attribute",
+                "path": "mail_intake.models.message.MailIntakeMessage.raw_headers",
+                "signature": null,
+                "docstring": "Normalized mapping of message headers (header name → value)."
+              }
+            }
+          }
+        }
+      },
+      "thread": {
+        "name": "thread",
+        "kind": "module",
+        "path": "mail_intake.models.thread",
+        "signature": null,
+        "docstring": "Thread 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.",
+        "members": {
+          "dataclass": {
+            "name": "dataclass",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.dataclass",
+            "signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
+            "docstring": null
+          },
+          "field": {
+            "name": "field",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.field",
+            "signature": "<bound method Alias.signature of Alias('field', 'dataclasses.field')>",
+            "docstring": null
+          },
+          "datetime": {
+            "name": "datetime",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.datetime",
+            "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
+            "docstring": null
+          },
+          "List": {
+            "name": "List",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.List",
+            "signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
+            "docstring": null
+          },
+          "Set": {
+            "name": "Set",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.Set",
+            "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
+            "docstring": null
+          },
+          "MailIntakeMessage": {
+            "name": "MailIntakeMessage",
+            "kind": "class",
+            "path": "mail_intake.models.thread.MailIntakeMessage",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
+            "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.",
+            "members": {
+              "message_id": {
+                "name": "message_id",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.message_id",
+                "signature": "<bound method Alias.signature of Alias('message_id', 'mail_intake.models.message.MailIntakeMessage.message_id')>",
+                "docstring": "Provider-specific message identifier."
+              },
+              "thread_id": {
+                "name": "thread_id",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.thread_id",
+                "signature": "<bound method Alias.signature of Alias('thread_id', 'mail_intake.models.message.MailIntakeMessage.thread_id')>",
+                "docstring": "Provider-specific thread identifier to which this message belongs."
+              },
+              "timestamp": {
+                "name": "timestamp",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.timestamp",
+                "signature": "<bound method Alias.signature of Alias('timestamp', 'mail_intake.models.message.MailIntakeMessage.timestamp')>",
+                "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": "<bound method Alias.signature of Alias('from_email', 'mail_intake.models.message.MailIntakeMessage.from_email')>",
+                "docstring": "Sender email address."
+              },
+              "from_name": {
+                "name": "from_name",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.from_name",
+                "signature": "<bound method Alias.signature of Alias('from_name', 'mail_intake.models.message.MailIntakeMessage.from_name')>",
+                "docstring": "Optional human-readable sender name."
+              },
+              "subject": {
+                "name": "subject",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.subject",
+                "signature": "<bound method Alias.signature of Alias('subject', 'mail_intake.models.message.MailIntakeMessage.subject')>",
+                "docstring": "Raw subject line of the message."
+              },
+              "body_text": {
+                "name": "body_text",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.body_text",
+                "signature": "<bound method Alias.signature of Alias('body_text', 'mail_intake.models.message.MailIntakeMessage.body_text')>",
+                "docstring": "Extracted plain-text body content of the message."
+              },
+              "snippet": {
+                "name": "snippet",
+                "kind": "attribute",
+                "path": "mail_intake.models.thread.MailIntakeMessage.snippet",
+                "signature": "<bound method Alias.signature of Alias('snippet', 'mail_intake.models.message.MailIntakeMessage.snippet')>",
+                "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": "<bound method Alias.signature of Alias('raw_headers', 'mail_intake.models.message.MailIntakeMessage.raw_headers')>",
+                "docstring": "Normalized mapping of message headers (header name → value)."
+              }
+            }
+          },
+          "MailIntakeThread": {
+            "name": "MailIntakeThread",
+            "kind": "class",
+            "path": "mail_intake.models.thread.MailIntakeThread",
+            "signature": "<bound method Class.signature of Class('MailIntakeThread', 18, 64)>",
+            "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis 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": "<bound method Function.signature of Function('add_message', 46, 64)>",
+                "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n    message: Parsed mail message to add to the thread."
+              }
+            }
+          },
+          "Optional": {
+            "name": "Optional",
+            "kind": "alias",
+            "path": "mail_intake.models.thread.Optional",
+            "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
+            "docstring": null
+          }
+        }
+      }
+    }
+  }
+}