mail-intake/docs/mcp/modules/mail_intake.parsers.json

{
  "module": "mail_intake.parsers",
  "content": {
    "path": "mail_intake.parsers",
    "docstring": "# Summary\n\nMessage parsing utilities for Mail Intake.\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n\n- Interpreting provider-native message structures.\n- Extracting meaningful fields such as headers, body text, and subjects.\n- Normalizing data into consistent internal representations.\n\nThis package does not:\n\n- Perform network or IO operations.\n- Contain provider API logic.\n- Construct domain models directly.\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.\n\n---\n\n# Public API\n\n- `extract_body`\n- `parse_headers`\n- `extract_sender`\n- `normalize_subject`\n\n---",
    "objects": {
      "extract_body": {
        "name": "extract_body",
        "kind": "function",
        "path": "mail_intake.parsers.extract_body",
        "signature": "extract_body(payload: dict[str, Any])",
        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
      },
      "parse_headers": {
        "name": "parse_headers",
        "kind": "function",
        "path": "mail_intake.parsers.parse_headers",
        "signature": "parse_headers(raw_headers: list[dict[str, str]])",
        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (list[dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
      },
      "extract_sender": {
        "name": "extract_sender",
        "kind": "function",
        "path": "mail_intake.parsers.extract_sender",
        "signature": "extract_sender(headers: dict[str, str])",
        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    tuple[str, str | None]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
      },
      "normalize_subject": {
        "name": "normalize_subject",
        "kind": "function",
        "path": "mail_intake.parsers.normalize_subject",
        "signature": "normalize_subject(subject: str)",
        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
      },
      "body": {
        "name": "body",
        "kind": "module",
        "path": "mail_intake.parsers.body",
        "signature": null,
        "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
        "members": {
          "MailIntakeParsingError": {
            "name": "MailIntakeParsingError",
            "kind": "class",
            "path": "mail_intake.parsers.body.MailIntakeParsingError",
            "signature": null,
            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
          },
          "extract_body": {
            "name": "extract_body",
            "kind": "function",
            "path": "mail_intake.parsers.body.extract_body",
            "signature": "extract_body(payload: dict[str, Any]) -> str",
            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
          }
        }
      },
      "headers": {
        "name": "headers",
        "kind": "module",
        "path": "mail_intake.parsers.headers",
        "signature": null,
        "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
        "members": {
          "parse_headers": {
            "name": "parse_headers",
            "kind": "function",
            "path": "mail_intake.parsers.headers.parse_headers",
            "signature": "parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]",
            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (list[dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
          },
          "extract_sender": {
            "name": "extract_sender",
            "kind": "function",
            "path": "mail_intake.parsers.headers.extract_sender",
            "signature": "extract_sender(headers: dict[str, str]) -> tuple[str, str | None]",
            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    tuple[str, str | None]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
          }
        }
      },
      "subject": {
        "name": "subject",
        "kind": "module",
        "path": "mail_intake.parsers.subject",
        "signature": null,
        "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
        "members": {
          "normalize_subject": {
            "name": "normalize_subject",
            "kind": "function",
            "path": "mail_intake.parsers.subject.normalize_subject",
            "signature": "normalize_subject(subject: str) -> str",
            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
          }
        }
      }
    }
  }
}