From b530276df2a4d774388e801fb83f34e1b12851d6 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sun, 13 Sep 2026 16:21:12 +0530 Subject: [PATCH] fix: GSDFC docstring conformance, modernize legacy typing to match signatures; regenerate lib/MCP docs (pydoclint zero) --- docs/lib/index.md | 1 + docs/lib/mail_intake/adapters/base.md | 3 + docs/lib/mail_intake/adapters/gmail.md | 3 + docs/lib/mail_intake/adapters/index.md | 5 + docs/lib/mail_intake/auth/base.md | 3 + docs/lib/mail_intake/auth/google.md | 3 + docs/lib/mail_intake/auth/index.md | 5 + docs/lib/mail_intake/config.md | 3 + docs/lib/mail_intake/credentials/index.md | 6 + docs/lib/mail_intake/credentials/pickle.md | 3 + docs/lib/mail_intake/credentials/redis.md | 3 + docs/lib/mail_intake/credentials/store.md | 3 + docs/lib/mail_intake/exceptions.md | 3 + docs/lib/mail_intake/index.md | 11 ++ docs/lib/mail_intake/ingestion/index.md | 4 + docs/lib/mail_intake/ingestion/reader.md | 3 + docs/lib/mail_intake/models/index.md | 5 + docs/lib/mail_intake/models/message.md | 3 + docs/lib/mail_intake/models/thread.md | 3 + docs/lib/mail_intake/parsers/body.md | 3 + docs/lib/mail_intake/parsers/headers.md | 3 + docs/lib/mail_intake/parsers/index.md | 6 + docs/lib/mail_intake/parsers/subject.md | 3 + .../modules/mail_intake.adapters.base.json | 14 +-- .../modules/mail_intake.adapters.gmail.json | 22 ++-- docs/mcp/modules/mail_intake.adapters.json | 50 ++++---- docs/mcp/modules/mail_intake.auth.google.json | 2 +- docs/mcp/modules/mail_intake.auth.json | 2 +- docs/mcp/modules/mail_intake.credentials.json | 24 ++-- .../mail_intake.credentials.pickle.json | 4 +- .../mail_intake.credentials.redis.json | 12 +- .../mail_intake.credentials.store.json | 2 +- docs/mcp/modules/mail_intake.exceptions.json | 10 +- docs/mcp/modules/mail_intake.ingestion.json | 16 +-- .../modules/mail_intake.ingestion.reader.json | 14 +-- docs/mcp/modules/mail_intake.json | 114 +++++++++--------- .../mcp/modules/mail_intake.parsers.body.json | 2 +- .../modules/mail_intake.parsers.headers.json | 4 +- docs/mcp/modules/mail_intake.parsers.json | 12 +- docs/mcp/nav.json | 44 +++---- mail_intake/adapters/base.py | 10 +- mail_intake/adapters/gmail.py | 10 +- mail_intake/credentials/pickle.py | 2 +- mail_intake/credentials/redis.py | 21 +--- mail_intake/credentials/store.py | 2 +- mail_intake/exceptions.py | 6 +- mail_intake/ingestion/reader.py | 8 +- mail_intake/parsers/body.py | 6 +- mail_intake/parsers/headers.py | 8 +- 49 files changed, 292 insertions(+), 217 deletions(-) create mode 100644 docs/lib/mail_intake/adapters/base.md create mode 100644 docs/lib/mail_intake/adapters/gmail.md create mode 100644 docs/lib/mail_intake/adapters/index.md create mode 100644 docs/lib/mail_intake/auth/base.md create mode 100644 docs/lib/mail_intake/auth/google.md create mode 100644 docs/lib/mail_intake/auth/index.md create mode 100644 docs/lib/mail_intake/config.md create mode 100644 docs/lib/mail_intake/credentials/index.md create mode 100644 docs/lib/mail_intake/credentials/pickle.md create mode 100644 docs/lib/mail_intake/credentials/redis.md create mode 100644 docs/lib/mail_intake/credentials/store.md create mode 100644 docs/lib/mail_intake/exceptions.md create mode 100644 docs/lib/mail_intake/index.md create mode 100644 docs/lib/mail_intake/ingestion/index.md create mode 100644 docs/lib/mail_intake/ingestion/reader.md create mode 100644 docs/lib/mail_intake/models/index.md create mode 100644 docs/lib/mail_intake/models/message.md create mode 100644 docs/lib/mail_intake/models/thread.md create mode 100644 docs/lib/mail_intake/parsers/body.md create mode 100644 docs/lib/mail_intake/parsers/headers.md create mode 100644 docs/lib/mail_intake/parsers/index.md create mode 100644 docs/lib/mail_intake/parsers/subject.md diff --git a/docs/lib/index.md b/docs/lib/index.md index cb976a8..7336caf 100644 --- a/docs/lib/index.md +++ b/docs/lib/index.md @@ -1,3 +1,4 @@ # mail_intake ::: mail_intake +- [Mail Intake](mail_intake/) diff --git a/docs/lib/mail_intake/adapters/base.md b/docs/lib/mail_intake/adapters/base.md new file mode 100644 index 0000000..309649c --- /dev/null +++ b/docs/lib/mail_intake/adapters/base.md @@ -0,0 +1,3 @@ +# Base + +::: mail_intake.adapters.base diff --git a/docs/lib/mail_intake/adapters/gmail.md b/docs/lib/mail_intake/adapters/gmail.md new file mode 100644 index 0000000..13818cc --- /dev/null +++ b/docs/lib/mail_intake/adapters/gmail.md @@ -0,0 +1,3 @@ +# Gmail + +::: mail_intake.adapters.gmail diff --git a/docs/lib/mail_intake/adapters/index.md b/docs/lib/mail_intake/adapters/index.md new file mode 100644 index 0000000..457cf71 --- /dev/null +++ b/docs/lib/mail_intake/adapters/index.md @@ -0,0 +1,5 @@ +# Adapters + +::: mail_intake.adapters +- [Base](base.md) +- [Gmail](gmail.md) diff --git a/docs/lib/mail_intake/auth/base.md b/docs/lib/mail_intake/auth/base.md new file mode 100644 index 0000000..a1da95e --- /dev/null +++ b/docs/lib/mail_intake/auth/base.md @@ -0,0 +1,3 @@ +# Base + +::: mail_intake.auth.base diff --git a/docs/lib/mail_intake/auth/google.md b/docs/lib/mail_intake/auth/google.md new file mode 100644 index 0000000..93e3086 --- /dev/null +++ b/docs/lib/mail_intake/auth/google.md @@ -0,0 +1,3 @@ +# Google + +::: mail_intake.auth.google diff --git a/docs/lib/mail_intake/auth/index.md b/docs/lib/mail_intake/auth/index.md new file mode 100644 index 0000000..29bed92 --- /dev/null +++ b/docs/lib/mail_intake/auth/index.md @@ -0,0 +1,5 @@ +# Auth + +::: mail_intake.auth +- [Base](base.md) +- [Google](google.md) diff --git a/docs/lib/mail_intake/config.md b/docs/lib/mail_intake/config.md new file mode 100644 index 0000000..355fbef --- /dev/null +++ b/docs/lib/mail_intake/config.md @@ -0,0 +1,3 @@ +# Config + +::: mail_intake.config diff --git a/docs/lib/mail_intake/credentials/index.md b/docs/lib/mail_intake/credentials/index.md new file mode 100644 index 0000000..a59e6ec --- /dev/null +++ b/docs/lib/mail_intake/credentials/index.md @@ -0,0 +1,6 @@ +# Credentials + +::: mail_intake.credentials +- [Pickle](pickle.md) +- [Redis](redis.md) +- [Store](store.md) diff --git a/docs/lib/mail_intake/credentials/pickle.md b/docs/lib/mail_intake/credentials/pickle.md new file mode 100644 index 0000000..36f450d --- /dev/null +++ b/docs/lib/mail_intake/credentials/pickle.md @@ -0,0 +1,3 @@ +# Pickle + +::: mail_intake.credentials.pickle diff --git a/docs/lib/mail_intake/credentials/redis.md b/docs/lib/mail_intake/credentials/redis.md new file mode 100644 index 0000000..a62ff87 --- /dev/null +++ b/docs/lib/mail_intake/credentials/redis.md @@ -0,0 +1,3 @@ +# Redis + +::: mail_intake.credentials.redis diff --git a/docs/lib/mail_intake/credentials/store.md b/docs/lib/mail_intake/credentials/store.md new file mode 100644 index 0000000..14d4841 --- /dev/null +++ b/docs/lib/mail_intake/credentials/store.md @@ -0,0 +1,3 @@ +# Store + +::: mail_intake.credentials.store diff --git a/docs/lib/mail_intake/exceptions.md b/docs/lib/mail_intake/exceptions.md new file mode 100644 index 0000000..6ac1bf2 --- /dev/null +++ b/docs/lib/mail_intake/exceptions.md @@ -0,0 +1,3 @@ +# Exceptions + +::: mail_intake.exceptions diff --git a/docs/lib/mail_intake/index.md b/docs/lib/mail_intake/index.md new file mode 100644 index 0000000..abc2259 --- /dev/null +++ b/docs/lib/mail_intake/index.md @@ -0,0 +1,11 @@ +# Mail Intake + +::: mail_intake +- [Adapters](adapters/) +- [Auth](auth/) +- [Config](config.md) +- [Credentials](credentials/) +- [Exceptions](exceptions.md) +- [Ingestion](ingestion/) +- [Models](models/) +- [Parsers](parsers/) diff --git a/docs/lib/mail_intake/ingestion/index.md b/docs/lib/mail_intake/ingestion/index.md new file mode 100644 index 0000000..7193c72 --- /dev/null +++ b/docs/lib/mail_intake/ingestion/index.md @@ -0,0 +1,4 @@ +# Ingestion + +::: mail_intake.ingestion +- [Reader](reader.md) diff --git a/docs/lib/mail_intake/ingestion/reader.md b/docs/lib/mail_intake/ingestion/reader.md new file mode 100644 index 0000000..690d9d9 --- /dev/null +++ b/docs/lib/mail_intake/ingestion/reader.md @@ -0,0 +1,3 @@ +# Reader + +::: mail_intake.ingestion.reader diff --git a/docs/lib/mail_intake/models/index.md b/docs/lib/mail_intake/models/index.md new file mode 100644 index 0000000..ea55662 --- /dev/null +++ b/docs/lib/mail_intake/models/index.md @@ -0,0 +1,5 @@ +# Models + +::: mail_intake.models +- [Message](message.md) +- [Thread](thread.md) diff --git a/docs/lib/mail_intake/models/message.md b/docs/lib/mail_intake/models/message.md new file mode 100644 index 0000000..b460397 --- /dev/null +++ b/docs/lib/mail_intake/models/message.md @@ -0,0 +1,3 @@ +# Message + +::: mail_intake.models.message diff --git a/docs/lib/mail_intake/models/thread.md b/docs/lib/mail_intake/models/thread.md new file mode 100644 index 0000000..74d3cc2 --- /dev/null +++ b/docs/lib/mail_intake/models/thread.md @@ -0,0 +1,3 @@ +# Thread + +::: mail_intake.models.thread diff --git a/docs/lib/mail_intake/parsers/body.md b/docs/lib/mail_intake/parsers/body.md new file mode 100644 index 0000000..2cf14af --- /dev/null +++ b/docs/lib/mail_intake/parsers/body.md @@ -0,0 +1,3 @@ +# Body + +::: mail_intake.parsers.body diff --git a/docs/lib/mail_intake/parsers/headers.md b/docs/lib/mail_intake/parsers/headers.md new file mode 100644 index 0000000..8192602 --- /dev/null +++ b/docs/lib/mail_intake/parsers/headers.md @@ -0,0 +1,3 @@ +# Headers + +::: mail_intake.parsers.headers diff --git a/docs/lib/mail_intake/parsers/index.md b/docs/lib/mail_intake/parsers/index.md new file mode 100644 index 0000000..b5e3b8e --- /dev/null +++ b/docs/lib/mail_intake/parsers/index.md @@ -0,0 +1,6 @@ +# Parsers + +::: mail_intake.parsers +- [Body](body.md) +- [Headers](headers.md) +- [Subject](subject.md) diff --git a/docs/lib/mail_intake/parsers/subject.md b/docs/lib/mail_intake/parsers/subject.md new file mode 100644 index 0000000..50bdd01 --- /dev/null +++ b/docs/lib/mail_intake/parsers/subject.md @@ -0,0 +1,3 @@ +# Subject + +::: mail_intake.parsers.subject diff --git a/docs/mcp/modules/mail_intake.adapters.base.json b/docs/mcp/modules/mail_intake.adapters.base.json index 8fbcdf8..3612a5b 100644 --- a/docs/mcp/modules/mail_intake.adapters.base.json +++ b/docs/mcp/modules/mail_intake.adapters.base.json @@ -36,29 +36,29 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } } diff --git a/docs/mcp/modules/mail_intake.adapters.gmail.json b/docs/mcp/modules/mail_intake.adapters.gmail.json index c3330f3..570317b 100644 --- a/docs/mcp/modules/mail_intake.adapters.gmail.json +++ b/docs/mcp/modules/mail_intake.adapters.gmail.json @@ -44,21 +44,21 @@ "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -89,7 +89,7 @@ "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -97,28 +97,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } diff --git a/docs/mcp/modules/mail_intake.adapters.json b/docs/mcp/modules/mail_intake.adapters.json index a37d7b0..7d52c53 100644 --- a/docs/mcp/modules/mail_intake.adapters.json +++ b/docs/mcp/modules/mail_intake.adapters.json @@ -16,21 +16,21 @@ "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -46,28 +46,28 @@ "kind": "attribute", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service", "signature": "", - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } }, @@ -110,29 +110,29 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } } @@ -185,21 +185,21 @@ "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -230,7 +230,7 @@ "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -238,28 +238,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } diff --git a/docs/mcp/modules/mail_intake.auth.google.json b/docs/mcp/modules/mail_intake.auth.google.json index 73c4003..4f2bba8 100644 --- a/docs/mcp/modules/mail_intake.auth.google.json +++ b/docs/mcp/modules/mail_intake.auth.google.json @@ -74,7 +74,7 @@ "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", diff --git a/docs/mcp/modules/mail_intake.auth.json b/docs/mcp/modules/mail_intake.auth.json index 4eaacbc..2981649 100644 --- a/docs/mcp/modules/mail_intake.auth.json +++ b/docs/mcp/modules/mail_intake.auth.json @@ -194,7 +194,7 @@ "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", diff --git a/docs/mcp/modules/mail_intake.credentials.json b/docs/mcp/modules/mail_intake.credentials.json index 3c9dba5..3d5a3b7 100644 --- a/docs/mcp/modules/mail_intake.credentials.json +++ b/docs/mcp/modules/mail_intake.credentials.json @@ -16,7 +16,7 @@ "kind": "function", "path": "mail_intake.credentials.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -53,7 +53,7 @@ "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.load", "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", @@ -118,7 +118,7 @@ "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.load", "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", @@ -169,7 +169,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -213,7 +213,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", @@ -266,7 +266,7 @@ "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -295,7 +295,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -337,21 +337,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } @@ -419,7 +419,7 @@ "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", diff --git a/docs/mcp/modules/mail_intake.credentials.pickle.json b/docs/mcp/modules/mail_intake.credentials.pickle.json index be98e2e..4813aad 100644 --- a/docs/mcp/modules/mail_intake.credentials.pickle.json +++ b/docs/mcp/modules/mail_intake.credentials.pickle.json @@ -30,7 +30,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -74,7 +74,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", diff --git a/docs/mcp/modules/mail_intake.credentials.redis.json b/docs/mcp/modules/mail_intake.credentials.redis.json index e6c6ae8..8c39459 100644 --- a/docs/mcp/modules/mail_intake.credentials.redis.json +++ b/docs/mcp/modules/mail_intake.credentials.redis.json @@ -30,7 +30,7 @@ "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -59,7 +59,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -101,21 +101,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } diff --git a/docs/mcp/modules/mail_intake.credentials.store.json b/docs/mcp/modules/mail_intake.credentials.store.json index 20e7ca8..1d527e5 100644 --- a/docs/mcp/modules/mail_intake.credentials.store.json +++ b/docs/mcp/modules/mail_intake.credentials.store.json @@ -51,7 +51,7 @@ "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", diff --git a/docs/mcp/modules/mail_intake.exceptions.json b/docs/mcp/modules/mail_intake.exceptions.json index 824d2f6..2fa2244 100644 --- a/docs/mcp/modules/mail_intake.exceptions.json +++ b/docs/mcp/modules/mail_intake.exceptions.json @@ -2,34 +2,34 @@ "module": "mail_intake.exceptions", "content": { "path": "mail_intake.exceptions", - "docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", + "docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", "objects": { "MailIntakeError": { "name": "MailIntakeError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeError", - "signature": "", + "signature": "", "docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures" }, "MailIntakeAuthError": { "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAuthError", - "signature": "", + "signature": "", "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeAdapterError": { "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAdapterError", - "signature": "", + "signature": "", "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, "MailIntakeParsingError": { "name": "MailIntakeParsingError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeParsingError", - "signature": "", + "signature": "", "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." } } diff --git a/docs/mcp/modules/mail_intake.ingestion.json b/docs/mcp/modules/mail_intake.ingestion.json index b1fe564..8cc077c 100644 --- a/docs/mcp/modules/mail_intake.ingestion.json +++ b/docs/mcp/modules/mail_intake.ingestion.json @@ -23,7 +23,7 @@ "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } }, @@ -67,21 +67,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -220,21 +220,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.extract_body", "signature": "", - "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." + "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." }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.ingestion.reader.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.ingestion.reader.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -262,7 +262,7 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } diff --git a/docs/mcp/modules/mail_intake.ingestion.reader.json b/docs/mcp/modules/mail_intake.ingestion.reader.json index 7027ee8..d870543 100644 --- a/docs/mcp/modules/mail_intake.ingestion.reader.json +++ b/docs/mcp/modules/mail_intake.ingestion.reader.json @@ -37,21 +37,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -190,21 +190,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.extract_body", "signature": "", - "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." + "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." }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.ingestion.reader.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.ingestion.reader.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -232,7 +232,7 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } diff --git a/docs/mcp/modules/mail_intake.json b/docs/mcp/modules/mail_intake.json index 425691e..ba08875 100644 --- a/docs/mcp/modules/mail_intake.json +++ b/docs/mcp/modules/mail_intake.json @@ -69,34 +69,34 @@ "kind": "module", "path": "mail_intake.exceptions", "signature": null, - "docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", + "docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", "members": { "MailIntakeError": { "name": "MailIntakeError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeError", - "signature": "", + "signature": "", "docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures" }, "MailIntakeAuthError": { "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAuthError", - "signature": "", + "signature": "", "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeAdapterError": { "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAdapterError", - "signature": "", + "signature": "", "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, "MailIntakeParsingError": { "name": "MailIntakeParsingError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeParsingError", - "signature": "", + "signature": "", "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." } } @@ -120,21 +120,21 @@ "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -150,28 +150,28 @@ "kind": "attribute", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service", "signature": "", - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } }, @@ -214,29 +214,29 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } } @@ -289,21 +289,21 @@ "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -334,7 +334,7 @@ "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -342,28 +342,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } @@ -568,7 +568,7 @@ "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -660,7 +660,7 @@ "kind": "function", "path": "mail_intake.credentials.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -697,7 +697,7 @@ "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.load", "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", @@ -762,7 +762,7 @@ "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.load", "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", @@ -813,7 +813,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -857,7 +857,7 @@ "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", @@ -910,7 +910,7 @@ "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -939,7 +939,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -981,21 +981,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } @@ -1063,7 +1063,7 @@ "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", @@ -1111,7 +1111,7 @@ "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } }, @@ -1155,21 +1155,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -1308,21 +1308,21 @@ "kind": "function", "path": "mail_intake.ingestion.reader.extract_body", "signature": "", - "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." + "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." }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.ingestion.reader.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.ingestion.reader.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -1350,7 +1350,7 @@ "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } @@ -1750,21 +1750,21 @@ "kind": "function", "path": "mail_intake.parsers.extract_body", "signature": "", - "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." + "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": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "normalize_subject": { "name": "normalize_subject", @@ -1813,7 +1813,7 @@ "kind": "function", "path": "mail_intake.parsers.body.extract_body", "signature": "", - "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." + "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." } } }, @@ -1829,14 +1829,14 @@ "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } }, diff --git a/docs/mcp/modules/mail_intake.parsers.body.json b/docs/mcp/modules/mail_intake.parsers.body.json index a8dffba..b0f11ab 100644 --- a/docs/mcp/modules/mail_intake.parsers.body.json +++ b/docs/mcp/modules/mail_intake.parsers.body.json @@ -37,7 +37,7 @@ "kind": "function", "path": "mail_intake.parsers.body.extract_body", "signature": "", - "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." + "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." } } } diff --git a/docs/mcp/modules/mail_intake.parsers.headers.json b/docs/mcp/modules/mail_intake.parsers.headers.json index e4f8230..71096fc 100644 --- a/docs/mcp/modules/mail_intake.parsers.headers.json +++ b/docs/mcp/modules/mail_intake.parsers.headers.json @@ -9,14 +9,14 @@ "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } } diff --git a/docs/mcp/modules/mail_intake.parsers.json b/docs/mcp/modules/mail_intake.parsers.json index 192b1f8..8a350b3 100644 --- a/docs/mcp/modules/mail_intake.parsers.json +++ b/docs/mcp/modules/mail_intake.parsers.json @@ -9,21 +9,21 @@ "kind": "function", "path": "mail_intake.parsers.extract_body", "signature": "", - "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." + "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": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "normalize_subject": { "name": "normalize_subject", @@ -72,7 +72,7 @@ "kind": "function", "path": "mail_intake.parsers.body.extract_body", "signature": "", - "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." + "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." } } }, @@ -88,14 +88,14 @@ "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", "signature": "", - "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "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 \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", "signature": "", - "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, Optional[str]]:\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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", 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 Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } }, diff --git a/docs/mcp/nav.json b/docs/mcp/nav.json index 10e1093..fe9270b 100644 --- a/docs/mcp/nav.json +++ b/docs/mcp/nav.json @@ -1,90 +1,90 @@ [ { "module": "mail_intake", - "resource": "doc://modules/mail_intake" + "resource": "docs://modules/mail_intake" }, { "module": "mail_intake.adapters", - "resource": "doc://modules/mail_intake.adapters" + "resource": "docs://modules/mail_intake.adapters" }, { "module": "mail_intake.adapters.base", - "resource": "doc://modules/mail_intake.adapters.base" + "resource": "docs://modules/mail_intake.adapters.base" }, { "module": "mail_intake.adapters.gmail", - "resource": "doc://modules/mail_intake.adapters.gmail" + "resource": "docs://modules/mail_intake.adapters.gmail" }, { "module": "mail_intake.auth", - "resource": "doc://modules/mail_intake.auth" + "resource": "docs://modules/mail_intake.auth" }, { "module": "mail_intake.auth.base", - "resource": "doc://modules/mail_intake.auth.base" + "resource": "docs://modules/mail_intake.auth.base" }, { "module": "mail_intake.auth.google", - "resource": "doc://modules/mail_intake.auth.google" + "resource": "docs://modules/mail_intake.auth.google" }, { "module": "mail_intake.config", - "resource": "doc://modules/mail_intake.config" + "resource": "docs://modules/mail_intake.config" }, { "module": "mail_intake.credentials", - "resource": "doc://modules/mail_intake.credentials" + "resource": "docs://modules/mail_intake.credentials" }, { "module": "mail_intake.credentials.pickle", - "resource": "doc://modules/mail_intake.credentials.pickle" + "resource": "docs://modules/mail_intake.credentials.pickle" }, { "module": "mail_intake.credentials.redis", - "resource": "doc://modules/mail_intake.credentials.redis" + "resource": "docs://modules/mail_intake.credentials.redis" }, { "module": "mail_intake.credentials.store", - "resource": "doc://modules/mail_intake.credentials.store" + "resource": "docs://modules/mail_intake.credentials.store" }, { "module": "mail_intake.exceptions", - "resource": "doc://modules/mail_intake.exceptions" + "resource": "docs://modules/mail_intake.exceptions" }, { "module": "mail_intake.ingestion", - "resource": "doc://modules/mail_intake.ingestion" + "resource": "docs://modules/mail_intake.ingestion" }, { "module": "mail_intake.ingestion.reader", - "resource": "doc://modules/mail_intake.ingestion.reader" + "resource": "docs://modules/mail_intake.ingestion.reader" }, { "module": "mail_intake.models", - "resource": "doc://modules/mail_intake.models" + "resource": "docs://modules/mail_intake.models" }, { "module": "mail_intake.models.message", - "resource": "doc://modules/mail_intake.models.message" + "resource": "docs://modules/mail_intake.models.message" }, { "module": "mail_intake.models.thread", - "resource": "doc://modules/mail_intake.models.thread" + "resource": "docs://modules/mail_intake.models.thread" }, { "module": "mail_intake.parsers", - "resource": "doc://modules/mail_intake.parsers" + "resource": "docs://modules/mail_intake.parsers" }, { "module": "mail_intake.parsers.body", - "resource": "doc://modules/mail_intake.parsers.body" + "resource": "docs://modules/mail_intake.parsers.body" }, { "module": "mail_intake.parsers.headers", - "resource": "doc://modules/mail_intake.parsers.headers" + "resource": "docs://modules/mail_intake.parsers.headers" }, { "module": "mail_intake.parsers.subject", - "resource": "doc://modules/mail_intake.parsers.subject" + "resource": "docs://modules/mail_intake.parsers.subject" } ] \ No newline at end of file diff --git a/mail_intake/adapters/base.py b/mail_intake/adapters/base.py index ce68e8c..1dd52cf 100644 --- a/mail_intake/adapters/base.py +++ b/mail_intake/adapters/base.py @@ -41,8 +41,12 @@ class MailIntakeAdapter(ABC): query (str): Provider-specific query string used to filter messages. + Returns: + Iterator[dict[str, str]]: + An iterator over lightweight message reference dictionaries. + Yields: - Dict[str, str]: + dict[str, str]: Dictionaries containing message and thread identifiers. Notes: @@ -73,7 +77,7 @@ class MailIntakeAdapter(ABC): Provider-specific message identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure). """ raise NotImplementedError @@ -88,7 +92,7 @@ class MailIntakeAdapter(ABC): Provider-specific thread identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native thread payload. """ raise NotImplementedError diff --git a/mail_intake/adapters/gmail.py b/mail_intake/adapters/gmail.py index 3fcbb7f..131cf62 100644 --- a/mail_intake/adapters/gmail.py +++ b/mail_intake/adapters/gmail.py @@ -72,10 +72,6 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): """ Lazily initialize and return the Gmail API service client. - Returns: - Any: - Initialized Gmail API service instance. - Raises: MailIntakeAdapterError: If the Gmail service cannot be initialized. @@ -99,7 +95,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail search query string. Yields: - Dict[str, str]: + dict[str, str]: Dictionaries containing ``message_id`` and ``thread_id``. Raises: @@ -136,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail message identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native Gmail message payload. Raises: @@ -164,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail thread identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native Gmail thread payload. Raises: diff --git a/mail_intake/credentials/pickle.py b/mail_intake/credentials/pickle.py index be4b35c..0021722 100644 --- a/mail_intake/credentials/pickle.py +++ b/mail_intake/credentials/pickle.py @@ -60,7 +60,7 @@ class PickleCredentialStore(CredentialStore[T]): Load credentials from the local filesystem. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are present and successfully deserialized; otherwise `None`. diff --git a/mail_intake/credentials/redis.py b/mail_intake/credentials/redis.py index 0853a5e..dcba383 100644 --- a/mail_intake/credentials/redis.py +++ b/mail_intake/credentials/redis.py @@ -66,21 +66,10 @@ class RedisCredentialStore(CredentialStore[T]): """ Initialize a Redis-backed credential store. - Args: - redis_client (Any): - An initialized Redis client instance (for example, ``redis.Redis`` or a compatible interface) used to communicate with the Redis server. - - key (str): - The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions. - - serialize (Callable[[T], bytes]): - A callable that converts a credential object of type ``T`` into a ``bytes`` representation suitable for storage in Redis. - - deserialize (Callable[[bytes], T]): - A callable that converts a ``bytes`` payload retrieved from Redis back into a credential object of type ``T``. - - ttl_seconds (Optional[int]): - Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If ``None``, credentials are stored without an expiration. + Callers supply all runtime dependencies: ``redis_client`` is an + initialized Redis client instance, ``key`` names the storage key, + ``serialize``/``deserialize`` are the encoding and decoding callables, + and ``ttl_seconds`` optionally limits credential lifetime. """ self.redis = redis_client self.key = key @@ -93,7 +82,7 @@ class RedisCredentialStore(CredentialStore[T]): Load credentials from Redis. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are present and successfully deserialized; otherwise `None`. diff --git a/mail_intake/credentials/store.py b/mail_intake/credentials/store.py index f6ffbaf..5ca720b 100644 --- a/mail_intake/credentials/store.py +++ b/mail_intake/credentials/store.py @@ -52,7 +52,7 @@ class CredentialStore(ABC, Generic[T]): Load previously persisted credentials. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are available and loadable; otherwise `None`. diff --git a/mail_intake/exceptions.py b/mail_intake/exceptions.py index fd98e0a..62b680d 100644 --- a/mail_intake/exceptions.py +++ b/mail_intake/exceptions.py @@ -1,10 +1,8 @@ """ +# Summary + Exception hierarchy for Mail Intake. ---- - -## Summary - This module defines the **canonical exception types** used throughout the Mail Intake library. diff --git a/mail_intake/ingestion/reader.py b/mail_intake/ingestion/reader.py index 23c35e9..25f0522 100644 --- a/mail_intake/ingestion/reader.py +++ b/mail_intake/ingestion/reader.py @@ -88,9 +88,9 @@ class MailIntakeReader: query (str): Provider-specific query string used to filter messages. - Yields: - MailIntakeThread: - An iterator of `MailIntakeThread` instances. + Returns: + Iterator[MailIntakeThread]: + An iterator over `MailIntakeThread` instances. Raises: `MailIntakeParsingError`: @@ -125,7 +125,7 @@ class MailIntakeReader: Parse a raw provider message into a `MailIntakeMessage`. Args: - raw_message (Dict[str, Any]): + raw_message (dict[str, Any]): Provider-native message payload. Returns: diff --git a/mail_intake/parsers/body.py b/mail_intake/parsers/body.py index 5101f66..4aa5f2f 100644 --- a/mail_intake/parsers/body.py +++ b/mail_intake/parsers/body.py @@ -55,11 +55,11 @@ def _extract_from_part(part: dict[str, Any]) -> str | None: - `text/html` (converted to plain text) Args: - part (Dict[str, Any]): + part (dict[str, Any]): MIME part dictionary from a provider payload. Returns: - Optional[str]: + str | None: Extracted plain-text content, or `None` if unsupported or empty. """ mime_type = part.get("mimeType") @@ -94,7 +94,7 @@ def extract_body(payload: dict[str, Any]) -> str: 4. Empty string (if nothing usable found) Args: - payload (Dict[str, Any]): + payload (dict[str, Any]): Provider-native message payload dictionary. Returns: diff --git a/mail_intake/parsers/headers.py b/mail_intake/parsers/headers.py index 418dc5a..4f1ac82 100644 --- a/mail_intake/parsers/headers.py +++ b/mail_intake/parsers/headers.py @@ -16,11 +16,11 @@ def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]: Convert a list of Gmail-style headers into a normalized dict. Args: - raw_headers (List[Dict[str, str]]): + raw_headers (list[dict[str, str]]): List of header dictionaries, each containing `name` and `value` keys. Returns: - Dict[str, str]: + dict[str, str]: Dictionary mapping lowercase header names to stripped values. Notes: @@ -67,11 +67,11 @@ def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]: Extract sender email and optional display name from headers. Args: - headers (Dict[str, str]): + headers (dict[str, str]): Normalized header dictionary as returned by `parse_headers()`. Returns: - Tuple[str, Optional[str]]: + tuple[str, str | None]: A tuple `(email, name)` where `email` is the sender email address and `name` is the display name, or `None` if unavailable.