docs: add wiki and refresh flat lib with mcp artifacts
- Add hand-written wiki (index, overview, how-to, extending, dev) following the platform anatomy - Remove stale nested docs/lib/mail_intake and regenerate the flat lib reference to match docforge.nav.yml - Regenerate MCP bundle with standardized docstrings
This commit is contained in:
@@ -8,28 +8,28 @@
|
||||
"name": "extract_body",
|
||||
"kind": "function",
|
||||
"path": "mail_intake.parsers.extract_body",
|
||||
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.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": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.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": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.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": {
|
||||
@@ -39,39 +39,18 @@
|
||||
"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": {
|
||||
"base64": {
|
||||
"name": "base64",
|
||||
"kind": "alias",
|
||||
"path": "mail_intake.parsers.body.base64",
|
||||
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Any": {
|
||||
"name": "Any",
|
||||
"kind": "alias",
|
||||
"path": "mail_intake.parsers.body.Any",
|
||||
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
|
||||
"docstring": null
|
||||
},
|
||||
"BeautifulSoup": {
|
||||
"name": "BeautifulSoup",
|
||||
"kind": "alias",
|
||||
"path": "mail_intake.parsers.body.BeautifulSoup",
|
||||
"signature": "<bound method Alias.signature of Alias('BeautifulSoup', 'bs4.BeautifulSoup')>",
|
||||
"docstring": null
|
||||
},
|
||||
"MailIntakeParsingError": {
|
||||
"name": "MailIntakeParsingError",
|
||||
"kind": "class",
|
||||
"path": "mail_intake.parsers.body.MailIntakeParsingError",
|
||||
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.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": "<bound method Function.signature of Function('extract_body', 85, 133)>",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
@@ -87,14 +66,14 @@
|
||||
"name": "parse_headers",
|
||||
"kind": "function",
|
||||
"path": "mail_intake.parsers.headers.parse_headers",
|
||||
"signature": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
|
||||
"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": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
|
||||
"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)`"
|
||||
}
|
||||
}
|
||||
@@ -106,18 +85,11 @@
|
||||
"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": {
|
||||
"re": {
|
||||
"name": "re",
|
||||
"kind": "alias",
|
||||
"path": "mail_intake.parsers.subject.re",
|
||||
"signature": "<bound method Alias.signature of Alias('re', 're')>",
|
||||
"docstring": null
|
||||
},
|
||||
"normalize_subject": {
|
||||
"name": "normalize_subject",
|
||||
"kind": "function",
|
||||
"path": "mail_intake.parsers.subject.normalize_subject",
|
||||
"signature": "<bound method Function.signature of Function('normalize_subject', 21, 61)>",
|
||||
"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."
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user