aetos/mail-intake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: GSDFC docstring conformance, modernize legacy typing to match signatures; regenerate lib/MCP docs (pydoclint zero)

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-13 16:21:12 +05:30
parent af8bb5add8
commit b530276df2
49 changed files with 292 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/lib/index.md
View File

@@ -1,3 +1,4 @@
# mail_intake
::: mail_intake
- [Mail Intake](mail_intake/)

3
docs/lib/mail_intake/adapters/base.md Normal file
View File

@@ -0,0 +1,3 @@
# Base
::: mail_intake.adapters.base

3
docs/lib/mail_intake/adapters/gmail.md Normal file
View File

@@ -0,0 +1,3 @@
# Gmail
::: mail_intake.adapters.gmail

5
docs/lib/mail_intake/adapters/index.md Normal file
View File

@@ -0,0 +1,5 @@
# Adapters
::: mail_intake.adapters
- [Base](base.md)
- [Gmail](gmail.md)

3
docs/lib/mail_intake/auth/base.md Normal file
View File

@@ -0,0 +1,3 @@
# Base
::: mail_intake.auth.base

3
docs/lib/mail_intake/auth/google.md Normal file
View File

@@ -0,0 +1,3 @@
# Google
::: mail_intake.auth.google

5
docs/lib/mail_intake/auth/index.md Normal file
View File

@@ -0,0 +1,5 @@
# Auth
::: mail_intake.auth
- [Base](base.md)
- [Google](google.md)

3
docs/lib/mail_intake/config.md Normal file
View File

@@ -0,0 +1,3 @@
# Config
::: mail_intake.config

6
docs/lib/mail_intake/credentials/index.md Normal file
View File

@@ -0,0 +1,6 @@
# Credentials
::: mail_intake.credentials
- [Pickle](pickle.md)
- [Redis](redis.md)
- [Store](store.md)

3
docs/lib/mail_intake/credentials/pickle.md Normal file
View File

@@ -0,0 +1,3 @@
# Pickle
::: mail_intake.credentials.pickle

3
docs/lib/mail_intake/credentials/redis.md Normal file
View File

@@ -0,0 +1,3 @@
# Redis
::: mail_intake.credentials.redis

3
docs/lib/mail_intake/credentials/store.md Normal file
View File

@@ -0,0 +1,3 @@
# Store
::: mail_intake.credentials.store

3
docs/lib/mail_intake/exceptions.md Normal file
View File

@@ -0,0 +1,3 @@
# Exceptions
::: mail_intake.exceptions

11
docs/lib/mail_intake/index.md Normal file
View File

@@ -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/)

4
docs/lib/mail_intake/ingestion/index.md Normal file
View File

@@ -0,0 +1,4 @@
# Ingestion
::: mail_intake.ingestion
- [Reader](reader.md)

3
docs/lib/mail_intake/ingestion/reader.md Normal file
View File

@@ -0,0 +1,3 @@
# Reader
::: mail_intake.ingestion.reader

5
docs/lib/mail_intake/models/index.md Normal file
View File

@@ -0,0 +1,5 @@
# Models
::: mail_intake.models
- [Message](message.md)
- [Thread](thread.md)

3
docs/lib/mail_intake/models/message.md Normal file
View File

@@ -0,0 +1,3 @@
# Message
::: mail_intake.models.message

3
docs/lib/mail_intake/models/thread.md Normal file
View File

@@ -0,0 +1,3 @@
# Thread
::: mail_intake.models.thread

3
docs/lib/mail_intake/parsers/body.md Normal file
View File

@@ -0,0 +1,3 @@
# Body
::: mail_intake.parsers.body

3
docs/lib/mail_intake/parsers/headers.md Normal file
View File

@@ -0,0 +1,3 @@
# Headers
::: mail_intake.parsers.headers

6
docs/lib/mail_intake/parsers/index.md Normal file
View File

@@ -0,0 +1,6 @@
# Parsers
::: mail_intake.parsers
- [Body](body.md)
- [Headers](headers.md)
- [Subject](subject.md)

3
docs/lib/mail_intake/parsers/subject.md Normal file
View File

@@ -0,0 +1,3 @@
# Subject
::: mail_intake.parsers.subject

14
docs/mcp/modules/mail_intake.adapters.base.json
View File

@@ -36,29 +36,29 @@
"name": "MailIntakeAdapter",
"kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 94)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 64)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"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": "<bound method Function.signature of Function('fetch_message', 66, 79)>",
"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": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"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": "<bound method Function.signature of Function('fetch_thread', 81, 94)>",
"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": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"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."
}
}
}

22
docs/mcp/modules/mail_intake.adapters.gmail.json
View File

@@ -44,21 +44,21 @@
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 184)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 93, 128)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"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": "<bound method Function.signature of Function('fetch_message', 130, 156)>",
"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": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"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": "<bound method Function.signature of Function('fetch_thread', 158, 184)>",
"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": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"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."
}
}
}

50
docs/mcp/modules/mail_intake.adapters.json
View File

@@ -16,21 +16,21 @@
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.service')>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread')>",
"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": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 94)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 64)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"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": "<bound method Function.signature of Function('fetch_message', 66, 79)>",
"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": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"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": "<bound method Function.signature of Function('fetch_thread', 81, 94)>",
"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": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 184)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 93, 128)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"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": "<bound method Function.signature of Function('fetch_message', 130, 156)>",
"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": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"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": "<bound method Function.signature of Function('fetch_thread', 158, 184)>",
"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": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"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."
}
}
}

2
docs/mcp/modules/mail_intake.auth.google.json
View File

@@ -74,7 +74,7 @@
"kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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",

2
docs/mcp/modules/mail_intake.auth.json
View File

@@ -194,7 +194,7 @@
"kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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",

24
docs/mcp/modules/mail_intake.credentials.json
View File

@@ -16,7 +16,7 @@
"kind": "function",
"path": "mail_intake.credentials.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Function.signature of Function('load', 58, 79)>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 137)>",
"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": "<bound method Function.signature of Function('load', 91, 116)>",
"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": "<bound method Function.signature of Function('load', 80, 105)>",
"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": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 107, 125)>",
"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": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 127, 137)>",
"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": "<bound method Function.signature of Function('load', 49, 67)>",
"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",

4
docs/mcp/modules/mail_intake.credentials.pickle.json
View File

@@ -30,7 +30,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Function.signature of Function('load', 58, 79)>",
"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",

12
docs/mcp/modules/mail_intake.credentials.redis.json
View File

@@ -30,7 +30,7 @@
"kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 137)>",
"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": "<bound method Function.signature of Function('load', 91, 116)>",
"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": "<bound method Function.signature of Function('load', 80, 105)>",
"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": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 107, 125)>",
"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": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 127, 137)>",
"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"
}
}

2
docs/mcp/modules/mail_intake.credentials.store.json
View File

@@ -51,7 +51,7 @@
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 49, 67)>",
"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",

10
docs/mcp/modules/mail_intake.exceptions.json
View File

@@ -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": "<bound method Class.signature of Class('MailIntakeError', 17, 27)>",
"signature": "<bound method Class.signature of Class('MailIntakeError', 15, 25)>",
"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": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 28, 37)>",
"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": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 40, 49)>",
"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": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 61)>",
"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."
}
}

16
docs/mcp/modules/mail_intake.ingestion.json
View File

@@ -23,7 +23,7 @@
"kind": "function",
"path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
"signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_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."
"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": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"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@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@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": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -262,7 +262,7 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"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."
}
}
}

14
docs/mcp/modules/mail_intake.ingestion.reader.json
View File

@@ -37,21 +37,21 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_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."
"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": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"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@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@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": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -232,7 +232,7 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"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."
}
}
}

114
docs/mcp/modules/mail_intake.json
View File

@@ -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": "<bound method Class.signature of Class('MailIntakeError', 17, 27)>",
"signature": "<bound method Class.signature of Class('MailIntakeError', 15, 25)>",
"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": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 28, 37)>",
"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": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 40, 49)>",
"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": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 61)>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.service')>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread')>",
"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": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 94)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 64)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"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": "<bound method Function.signature of Function('fetch_message', 66, 79)>",
"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": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"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": "<bound method Function.signature of Function('fetch_thread', 81, 94)>",
"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": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 184)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 93, 128)>",
"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": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"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": "<bound method Function.signature of Function('fetch_message', 130, 156)>",
"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": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"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": "<bound method Function.signature of Function('fetch_thread', 158, 184)>",
"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": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Function.signature of Function('load', 58, 79)>",
"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": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"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": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 137)>",
"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": "<bound method Function.signature of Function('load', 91, 116)>",
"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": "<bound method Function.signature of Function('load', 80, 105)>",
"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": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 107, 125)>",
"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": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 127, 137)>",
"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": "<bound method Function.signature of Function('load', 49, 67)>",
"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": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
"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": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"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": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"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": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"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": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_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."
"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": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"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@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@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": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -1350,7 +1350,7 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"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": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_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."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"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@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@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": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"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": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"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@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@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
},

2
docs/mcp/modules/mail_intake.parsers.body.json
View File

@@ -37,7 +37,7 @@
"kind": "function",
"path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"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."
}
}
}

4
docs/mcp/modules/mail_intake.parsers.headers.json
View File

@@ -9,14 +9,14 @@
"kind": "function",
"path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"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@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@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
}

12
docs/mcp/modules/mail_intake.parsers.json
View File

@@ -9,21 +9,21 @@
"kind": "function",
"path": "mail_intake.parsers.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_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."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"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@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@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": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"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": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"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@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@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
},

44
docs/mcp/nav.json
View File

@@ -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"
}
]