From fd73c312d6cae8bfc165b2cf829ac9cac1a262e2 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Thu, 10 Sep 2026 21:15:48 +0530 Subject: [PATCH] docs: nest generated docs under docs/lib and docs/mcp --- docs/{ => lib}/adapters/base.md | 0 docs/{ => lib}/adapters/gmail.md | 0 docs/{ => lib}/adapters/index.md | 0 docs/{ => lib}/auth/base.md | 0 docs/{ => lib}/auth/google.md | 0 docs/{ => lib}/auth/index.md | 0 docs/{ => lib}/config.md | 0 docs/{ => lib}/credentials/index.md | 0 docs/{ => lib}/credentials/pickle.md | 0 docs/{ => lib}/credentials/redis.md | 0 docs/{ => lib}/credentials/store.md | 0 docs/{ => lib}/exceptions.md | 0 docs/{ => lib}/index.md | 0 docs/{ => lib}/ingestion/index.md | 0 docs/{ => lib}/ingestion/reader.md | 0 docs/{ => lib}/models/index.md | 0 docs/{ => lib}/models/message.md | 0 docs/{ => lib}/models/thread.md | 0 docs/{ => lib}/parsers/body.md | 0 docs/{ => lib}/parsers/headers.md | 0 docs/{ => lib}/parsers/index.md | 0 docs/{ => lib}/parsers/subject.md | 0 {mcp_docs => docs/mcp}/index.json | 0 .../modules/mail_intake.adapters.base.json | 17 +- .../modules/mail_intake.adapters.gmail.json | 31 +-- .../mcp}/modules/mail_intake.adapters.json | 48 ++-- .../mcp}/modules/mail_intake.auth.base.json | 0 .../mcp}/modules/mail_intake.auth.google.json | 16 +- .../mcp}/modules/mail_intake.auth.json | 16 +- .../mcp}/modules/mail_intake.config.json | 9 +- .../mcp}/modules/mail_intake.credentials.json | 37 +-- .../mail_intake.credentials.pickle.json | 7 - .../mail_intake.credentials.redis.json | 15 +- .../mail_intake.credentials.store.json | 15 +- .../mcp}/modules/mail_intake.exceptions.json | 0 .../mcp}/modules/mail_intake.ingestion.json | 61 ++-- .../modules/mail_intake.ingestion.reader.json | 61 ++-- .../mcp}/modules/mail_intake.json | 260 +++++------------- .../mcp}/modules/mail_intake.models.json | 41 +-- .../modules/mail_intake.models.message.json | 16 +- .../modules/mail_intake.models.thread.json | 25 +- .../modules/mail_intake.parsers.body.json | 14 - .../modules/mail_intake.parsers.headers.json | 32 +-- .../mcp}/modules/mail_intake.parsers.json | 48 +--- .../modules/mail_intake.parsers.subject.json | 2 +- {mcp_docs => docs/mcp}/nav.json | 0 mkdocs.yml | 1 + 47 files changed, 201 insertions(+), 571 deletions(-) rename docs/{ => lib}/adapters/base.md (100%) rename docs/{ => lib}/adapters/gmail.md (100%) rename docs/{ => lib}/adapters/index.md (100%) rename docs/{ => lib}/auth/base.md (100%) rename docs/{ => lib}/auth/google.md (100%) rename docs/{ => lib}/auth/index.md (100%) rename docs/{ => lib}/config.md (100%) rename docs/{ => lib}/credentials/index.md (100%) rename docs/{ => lib}/credentials/pickle.md (100%) rename docs/{ => lib}/credentials/redis.md (100%) rename docs/{ => lib}/credentials/store.md (100%) rename docs/{ => lib}/exceptions.md (100%) rename docs/{ => lib}/index.md (100%) rename docs/{ => lib}/ingestion/index.md (100%) rename docs/{ => lib}/ingestion/reader.md (100%) rename docs/{ => lib}/models/index.md (100%) rename docs/{ => lib}/models/message.md (100%) rename docs/{ => lib}/models/thread.md (100%) rename docs/{ => lib}/parsers/body.md (100%) rename docs/{ => lib}/parsers/headers.md (100%) rename docs/{ => lib}/parsers/index.md (100%) rename docs/{ => lib}/parsers/subject.md (100%) rename {mcp_docs => docs/mcp}/index.json (100%) rename {mcp_docs => docs/mcp}/modules/mail_intake.adapters.base.json (90%) rename {mcp_docs => docs/mcp}/modules/mail_intake.adapters.gmail.json (96%) rename {mcp_docs => docs/mcp}/modules/mail_intake.adapters.json (95%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.base.json (100%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.google.json (99%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.json (99%) rename {mcp_docs => docs/mcp}/modules/mail_intake.config.json (91%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.json (97%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.pickle.json (96%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.redis.json (97%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.store.json (93%) rename {mcp_docs => docs/mcp}/modules/mail_intake.exceptions.json (100%) rename {mcp_docs => docs/mcp}/modules/mail_intake.ingestion.json (98%) rename {mcp_docs => docs/mcp}/modules/mail_intake.ingestion.reader.json (98%) rename {mcp_docs => docs/mcp}/modules/mail_intake.json (95%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.json (93%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.message.json (89%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.thread.json (91%) rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.body.json (82%) rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.headers.json (71%) rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.json (87%) rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.subject.json (97%) rename {mcp_docs => docs/mcp}/nav.json (100%) diff --git a/docs/adapters/base.md b/docs/lib/adapters/base.md similarity index 100% rename from docs/adapters/base.md rename to docs/lib/adapters/base.md diff --git a/docs/adapters/gmail.md b/docs/lib/adapters/gmail.md similarity index 100% rename from docs/adapters/gmail.md rename to docs/lib/adapters/gmail.md diff --git a/docs/adapters/index.md b/docs/lib/adapters/index.md similarity index 100% rename from docs/adapters/index.md rename to docs/lib/adapters/index.md diff --git a/docs/auth/base.md b/docs/lib/auth/base.md similarity index 100% rename from docs/auth/base.md rename to docs/lib/auth/base.md diff --git a/docs/auth/google.md b/docs/lib/auth/google.md similarity index 100% rename from docs/auth/google.md rename to docs/lib/auth/google.md diff --git a/docs/auth/index.md b/docs/lib/auth/index.md similarity index 100% rename from docs/auth/index.md rename to docs/lib/auth/index.md diff --git a/docs/config.md b/docs/lib/config.md similarity index 100% rename from docs/config.md rename to docs/lib/config.md diff --git a/docs/credentials/index.md b/docs/lib/credentials/index.md similarity index 100% rename from docs/credentials/index.md rename to docs/lib/credentials/index.md diff --git a/docs/credentials/pickle.md b/docs/lib/credentials/pickle.md similarity index 100% rename from docs/credentials/pickle.md rename to docs/lib/credentials/pickle.md diff --git a/docs/credentials/redis.md b/docs/lib/credentials/redis.md similarity index 100% rename from docs/credentials/redis.md rename to docs/lib/credentials/redis.md diff --git a/docs/credentials/store.md b/docs/lib/credentials/store.md similarity index 100% rename from docs/credentials/store.md rename to docs/lib/credentials/store.md diff --git a/docs/exceptions.md b/docs/lib/exceptions.md similarity index 100% rename from docs/exceptions.md rename to docs/lib/exceptions.md diff --git a/docs/index.md b/docs/lib/index.md similarity index 100% rename from docs/index.md rename to docs/lib/index.md diff --git a/docs/ingestion/index.md b/docs/lib/ingestion/index.md similarity index 100% rename from docs/ingestion/index.md rename to docs/lib/ingestion/index.md diff --git a/docs/ingestion/reader.md b/docs/lib/ingestion/reader.md similarity index 100% rename from docs/ingestion/reader.md rename to docs/lib/ingestion/reader.md diff --git a/docs/models/index.md b/docs/lib/models/index.md similarity index 100% rename from docs/models/index.md rename to docs/lib/models/index.md diff --git a/docs/models/message.md b/docs/lib/models/message.md similarity index 100% rename from docs/models/message.md rename to docs/lib/models/message.md diff --git a/docs/models/thread.md b/docs/lib/models/thread.md similarity index 100% rename from docs/models/thread.md rename to docs/lib/models/thread.md diff --git a/docs/parsers/body.md b/docs/lib/parsers/body.md similarity index 100% rename from docs/parsers/body.md rename to docs/lib/parsers/body.md diff --git a/docs/parsers/headers.md b/docs/lib/parsers/headers.md similarity index 100% rename from docs/parsers/headers.md rename to docs/lib/parsers/headers.md diff --git a/docs/parsers/index.md b/docs/lib/parsers/index.md similarity index 100% rename from docs/parsers/index.md rename to docs/lib/parsers/index.md diff --git a/docs/parsers/subject.md b/docs/lib/parsers/subject.md similarity index 100% rename from docs/parsers/subject.md rename to docs/lib/parsers/subject.md diff --git a/mcp_docs/index.json b/docs/mcp/index.json similarity index 100% rename from mcp_docs/index.json rename to docs/mcp/index.json diff --git a/mcp_docs/modules/mail_intake.adapters.base.json b/docs/mcp/modules/mail_intake.adapters.base.json similarity index 90% rename from mcp_docs/modules/mail_intake.adapters.base.json rename to docs/mcp/modules/mail_intake.adapters.base.json index 442d30b..8fbcdf8 100644 --- a/mcp_docs/modules/mail_intake.adapters.base.json +++ b/docs/mcp/modules/mail_intake.adapters.base.json @@ -22,14 +22,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.base.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.base.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -43,28 +36,28 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." } } diff --git a/mcp_docs/modules/mail_intake.adapters.gmail.json b/docs/mcp/modules/mail_intake.adapters.gmail.json similarity index 96% rename from mcp_docs/modules/mail_intake.adapters.gmail.json rename to docs/mcp/modules/mail_intake.adapters.gmail.json index 7dcb866..c3330f3 100644 --- a/mcp_docs/modules/mail_intake.adapters.gmail.json +++ b/docs/mcp/modules/mail_intake.adapters.gmail.json @@ -8,14 +8,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.gmail.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.gmail.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -69,13 +62,6 @@ } } }, - "MailIntakeAdapterError": { - "name": "MailIntakeAdapterError", - "kind": "class", - "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", - "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." - }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", @@ -92,11 +78,18 @@ } } }, + "MailIntakeAdapterError": { + "name": "MailIntakeAdapterError", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", + "signature": "", + "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." + }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -110,21 +103,21 @@ "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } diff --git a/mcp_docs/modules/mail_intake.adapters.json b/docs/mcp/modules/mail_intake.adapters.json similarity index 95% rename from mcp_docs/modules/mail_intake.adapters.json rename to docs/mcp/modules/mail_intake.adapters.json index 7fc236c..a37d7b0 100644 --- a/mcp_docs/modules/mail_intake.adapters.json +++ b/docs/mcp/modules/mail_intake.adapters.json @@ -96,14 +96,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.base.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.base.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -117,28 +110,28 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." } } @@ -156,14 +149,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.gmail.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.gmail.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -217,13 +203,6 @@ } } }, - "MailIntakeAdapterError": { - "name": "MailIntakeAdapterError", - "kind": "class", - "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", - "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." - }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", @@ -240,11 +219,18 @@ } } }, + "MailIntakeAdapterError": { + "name": "MailIntakeAdapterError", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", + "signature": "", + "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." + }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -258,21 +244,21 @@ "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } diff --git a/mcp_docs/modules/mail_intake.auth.base.json b/docs/mcp/modules/mail_intake.auth.base.json similarity index 100% rename from mcp_docs/modules/mail_intake.auth.base.json rename to docs/mcp/modules/mail_intake.auth.base.json diff --git a/mcp_docs/modules/mail_intake.auth.google.json b/docs/mcp/modules/mail_intake.auth.google.json similarity index 99% rename from mcp_docs/modules/mail_intake.auth.google.json rename to docs/mcp/modules/mail_intake.auth.google.json index 7b8baa2..73c4003 100644 --- a/mcp_docs/modules/mail_intake.auth.google.json +++ b/docs/mcp/modules/mail_intake.auth.google.json @@ -15,7 +15,7 @@ "name": "Sequence", "kind": "alias", "path": "mail_intake.auth.google.Sequence", - "signature": "", + "signature": "", "docstring": null }, "google": { @@ -32,13 +32,6 @@ "signature": "", "docstring": null }, - "InstalledAppFlow": { - "name": "InstalledAppFlow", - "kind": "alias", - "path": "mail_intake.auth.google.InstalledAppFlow", - "signature": "", - "docstring": null - }, "Credentials": { "name": "Credentials", "kind": "alias", @@ -46,6 +39,13 @@ "signature": "", "docstring": null }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", diff --git a/mcp_docs/modules/mail_intake.auth.json b/docs/mcp/modules/mail_intake.auth.json similarity index 99% rename from mcp_docs/modules/mail_intake.auth.json rename to docs/mcp/modules/mail_intake.auth.json index 0a4263b..4eaacbc 100644 --- a/mcp_docs/modules/mail_intake.auth.json +++ b/docs/mcp/modules/mail_intake.auth.json @@ -135,7 +135,7 @@ "name": "Sequence", "kind": "alias", "path": "mail_intake.auth.google.Sequence", - "signature": "", + "signature": "", "docstring": null }, "google": { @@ -152,13 +152,6 @@ "signature": "", "docstring": null }, - "InstalledAppFlow": { - "name": "InstalledAppFlow", - "kind": "alias", - "path": "mail_intake.auth.google.InstalledAppFlow", - "signature": "", - "docstring": null - }, "Credentials": { "name": "Credentials", "kind": "alias", @@ -166,6 +159,13 @@ "signature": "", "docstring": null }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", diff --git a/mcp_docs/modules/mail_intake.config.json b/docs/mcp/modules/mail_intake.config.json similarity index 91% rename from mcp_docs/modules/mail_intake.config.json rename to docs/mcp/modules/mail_intake.config.json index e027f04..0bf2561 100644 --- a/mcp_docs/modules/mail_intake.config.json +++ b/docs/mcp/modules/mail_intake.config.json @@ -11,18 +11,11 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.config.Optional", - "signature": "", - "docstring": null - }, "MailIntakeConfig": { "name": "MailIntakeConfig", "kind": "class", "path": "mail_intake.config.MailIntakeConfig", - "signature": "", + "signature": "", "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.", "members": { "provider": { diff --git a/mcp_docs/modules/mail_intake.credentials.json b/docs/mcp/modules/mail_intake.credentials.json similarity index 97% rename from mcp_docs/modules/mail_intake.credentials.json rename to docs/mcp/modules/mail_intake.credentials.json index df9d409..3c9dba5 100644 --- a/mcp_docs/modules/mail_intake.credentials.json +++ b/docs/mcp/modules/mail_intake.credentials.json @@ -150,13 +150,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.pickle.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -247,11 +240,11 @@ "signature": null, "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "members": { - "Optional": { - "name": "Optional", + "Callable": { + "name": "Callable", "kind": "alias", - "path": "mail_intake.credentials.redis.Optional", - "signature": "", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", "docstring": null }, "TypeVar": { @@ -261,13 +254,6 @@ "signature": "", "docstring": null }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "mail_intake.credentials.redis.Callable", - "signature": "", - "docstring": null - }, "CredentialStore": { "name": "CredentialStore", "kind": "class", @@ -407,13 +393,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.store.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -432,28 +411,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": "", "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } diff --git a/mcp_docs/modules/mail_intake.credentials.pickle.json b/docs/mcp/modules/mail_intake.credentials.pickle.json similarity index 96% rename from mcp_docs/modules/mail_intake.credentials.pickle.json rename to docs/mcp/modules/mail_intake.credentials.pickle.json index 16e8c40..be98e2e 100644 --- a/mcp_docs/modules/mail_intake.credentials.pickle.json +++ b/docs/mcp/modules/mail_intake.credentials.pickle.json @@ -11,13 +11,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.pickle.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", diff --git a/mcp_docs/modules/mail_intake.credentials.redis.json b/docs/mcp/modules/mail_intake.credentials.redis.json similarity index 97% rename from mcp_docs/modules/mail_intake.credentials.redis.json rename to docs/mcp/modules/mail_intake.credentials.redis.json index f2bbbfa..e6c6ae8 100644 --- a/mcp_docs/modules/mail_intake.credentials.redis.json +++ b/docs/mcp/modules/mail_intake.credentials.redis.json @@ -4,11 +4,11 @@ "path": "mail_intake.credentials.redis", "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "objects": { - "Optional": { - "name": "Optional", + "Callable": { + "name": "Callable", "kind": "alias", - "path": "mail_intake.credentials.redis.Optional", - "signature": "", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", "docstring": null }, "TypeVar": { @@ -18,13 +18,6 @@ "signature": "", "docstring": null }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "mail_intake.credentials.redis.Callable", - "signature": "", - "docstring": null - }, "CredentialStore": { "name": "CredentialStore", "kind": "class", diff --git a/mcp_docs/modules/mail_intake.credentials.store.json b/docs/mcp/modules/mail_intake.credentials.store.json similarity index 93% rename from mcp_docs/modules/mail_intake.credentials.store.json rename to docs/mcp/modules/mail_intake.credentials.store.json index efc7fed..20e7ca8 100644 --- a/mcp_docs/modules/mail_intake.credentials.store.json +++ b/docs/mcp/modules/mail_intake.credentials.store.json @@ -25,13 +25,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.store.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -50,28 +43,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": "", "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } diff --git a/mcp_docs/modules/mail_intake.exceptions.json b/docs/mcp/modules/mail_intake.exceptions.json similarity index 100% rename from mcp_docs/modules/mail_intake.exceptions.json rename to docs/mcp/modules/mail_intake.exceptions.json diff --git a/mcp_docs/modules/mail_intake.ingestion.json b/docs/mcp/modules/mail_intake.ingestion.json similarity index 98% rename from mcp_docs/modules/mail_intake.ingestion.json rename to docs/mcp/modules/mail_intake.ingestion.json index eb08b63..b1fe564 100644 --- a/mcp_docs/modules/mail_intake.ingestion.json +++ b/docs/mcp/modules/mail_intake.ingestion.json @@ -34,6 +34,13 @@ "signature": null, "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "members": { + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, "datetime": { "name": "datetime", "kind": "alias", @@ -41,20 +48,6 @@ "signature": "", "docstring": null }, - "Iterator": { - "name": "Iterator", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -92,6 +85,13 @@ } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -215,12 +215,12 @@ } } }, - "parse_headers": { - "name": "parse_headers", + "extract_body": { + "name": "extract_body", "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." }, "extract_sender": { "name": "extract_sender", @@ -229,12 +229,12 @@ "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, - "extract_body": { - "name": "extract_body", + "parse_headers": { + "name": "parse_headers", "kind": "function", - "path": "mail_intake.ingestion.reader.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -243,32 +243,25 @@ "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", + "signature": "", "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } diff --git a/mcp_docs/modules/mail_intake.ingestion.reader.json b/docs/mcp/modules/mail_intake.ingestion.reader.json similarity index 98% rename from mcp_docs/modules/mail_intake.ingestion.reader.json rename to docs/mcp/modules/mail_intake.ingestion.reader.json index 0312193..7027ee8 100644 --- a/mcp_docs/modules/mail_intake.ingestion.reader.json +++ b/docs/mcp/modules/mail_intake.ingestion.reader.json @@ -4,6 +4,13 @@ "path": "mail_intake.ingestion.reader", "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "objects": { + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, "datetime": { "name": "datetime", "kind": "alias", @@ -11,20 +18,6 @@ "signature": "", "docstring": null }, - "Iterator": { - "name": "Iterator", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -62,6 +55,13 @@ } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -185,12 +185,12 @@ } } }, - "parse_headers": { - "name": "parse_headers", + "extract_body": { + "name": "extract_body", "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." }, "extract_sender": { "name": "extract_sender", @@ -199,12 +199,12 @@ "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, - "extract_body": { - "name": "extract_body", + "parse_headers": { + "name": "parse_headers", "kind": "function", - "path": "mail_intake.ingestion.reader.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -213,32 +213,25 @@ "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", + "signature": "", "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } diff --git a/mcp_docs/modules/mail_intake.json b/docs/mcp/modules/mail_intake.json similarity index 95% rename from mcp_docs/modules/mail_intake.json rename to docs/mcp/modules/mail_intake.json index 03d7213..425691e 100644 --- a/mcp_docs/modules/mail_intake.json +++ b/docs/mcp/modules/mail_intake.json @@ -18,18 +18,11 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.config.Optional", - "signature": "", - "docstring": null - }, "MailIntakeConfig": { "name": "MailIntakeConfig", "kind": "class", "path": "mail_intake.config.MailIntakeConfig", - "signature": "", + "signature": "", "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.", "members": { "provider": { @@ -207,14 +200,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.base.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.base.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -228,28 +214,28 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.base.MailIntakeAdapter", - "signature": "", + "signature": "", "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." } } @@ -267,14 +253,7 @@ "name": "Iterator", "kind": "alias", "path": "mail_intake.adapters.gmail.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.adapters.gmail.Dict", - "signature": "", + "signature": "", "docstring": null }, "Any": { @@ -328,13 +307,6 @@ } } }, - "MailIntakeAdapterError": { - "name": "MailIntakeAdapterError", - "kind": "class", - "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", - "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." - }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", @@ -351,11 +323,18 @@ } } }, + "MailIntakeAdapterError": { + "name": "MailIntakeAdapterError", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", + "signature": "", + "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." + }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -369,21 +348,21 @@ "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", + "signature": "", "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", + "signature": "", "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } @@ -530,7 +509,7 @@ "name": "Sequence", "kind": "alias", "path": "mail_intake.auth.google.Sequence", - "signature": "", + "signature": "", "docstring": null }, "google": { @@ -547,13 +526,6 @@ "signature": "", "docstring": null }, - "InstalledAppFlow": { - "name": "InstalledAppFlow", - "kind": "alias", - "path": "mail_intake.auth.google.InstalledAppFlow", - "signature": "", - "docstring": null - }, "Credentials": { "name": "Credentials", "kind": "alias", @@ -561,6 +533,13 @@ "signature": "", "docstring": null }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, "MailIntakeAuthProvider": { "name": "MailIntakeAuthProvider", "kind": "class", @@ -815,13 +794,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.pickle.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -912,11 +884,11 @@ "signature": null, "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "members": { - "Optional": { - "name": "Optional", + "Callable": { + "name": "Callable", "kind": "alias", - "path": "mail_intake.credentials.redis.Optional", - "signature": "", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", "docstring": null }, "TypeVar": { @@ -926,13 +898,6 @@ "signature": "", "docstring": null }, - "Callable": { - "name": "Callable", - "kind": "alias", - "path": "mail_intake.credentials.redis.Callable", - "signature": "", - "docstring": null - }, "CredentialStore": { "name": "CredentialStore", "kind": "class", @@ -1072,13 +1037,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.credentials.store.Optional", - "signature": "", - "docstring": null - }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -1097,28 +1055,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": "", "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -1164,6 +1122,13 @@ "signature": null, "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "members": { + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, "datetime": { "name": "datetime", "kind": "alias", @@ -1171,20 +1136,6 @@ "signature": "", "docstring": null }, - "Iterator": { - "name": "Iterator", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Iterator", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.ingestion.reader.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -1222,6 +1173,13 @@ } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -1345,12 +1303,12 @@ } } }, - "parse_headers": { - "name": "parse_headers", + "extract_body": { + "name": "extract_body", "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." }, "extract_sender": { "name": "extract_sender", @@ -1359,12 +1317,12 @@ "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, - "extract_body": { - "name": "extract_body", + "parse_headers": { + "name": "parse_headers", "kind": "function", - "path": "mail_intake.ingestion.reader.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", @@ -1373,32 +1331,25 @@ "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", + "signature": "", "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } @@ -1558,25 +1509,11 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.message.Optional", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.models.message.Dict", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.models.message.MailIntakeMessage", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { @@ -1674,20 +1611,6 @@ "signature": "", "docstring": null }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.models.thread.List", - "signature": "", - "docstring": null - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "mail_intake.models.thread.Set", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -1764,7 +1687,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -1806,17 +1729,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } @@ -1871,13 +1787,6 @@ "signature": "", "docstring": null }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.body.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -1885,13 +1794,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.body.Optional", - "signature": "", - "docstring": null - }, "BeautifulSoup": { "name": "BeautifulSoup", "kind": "alias", @@ -1922,46 +1824,18 @@ "signature": null, "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", "members": { - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.headers.Dict", - "signature": "", - "docstring": null - }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.parsers.headers.List", - "signature": "", - "docstring": null - }, - "Tuple": { - "name": "Tuple", - "kind": "alias", - "path": "mail_intake.parsers.headers.Tuple", - "signature": "", - "docstring": null - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.headers.Optional", - "signature": "", - "docstring": null - }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", - "signature": "", + "signature": "", "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", + "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } @@ -1984,7 +1858,7 @@ "name": "normalize_subject", "kind": "function", "path": "mail_intake.parsers.subject.normalize_subject", - "signature": "", + "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/mcp_docs/modules/mail_intake.models.json b/docs/mcp/modules/mail_intake.models.json similarity index 93% rename from mcp_docs/modules/mail_intake.models.json rename to docs/mcp/modules/mail_intake.models.json index 9cf05a6..f33e351 100644 --- a/mcp_docs/modules/mail_intake.models.json +++ b/docs/mcp/modules/mail_intake.models.json @@ -148,25 +148,11 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.message.Optional", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.models.message.Dict", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.models.message.MailIntakeMessage", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { @@ -264,20 +250,6 @@ "signature": "", "docstring": null }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.models.thread.List", - "signature": "", - "docstring": null - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "mail_intake.models.thread.Set", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -354,7 +326,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -396,17 +368,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.models.message.json b/docs/mcp/modules/mail_intake.models.message.json similarity index 89% rename from mcp_docs/modules/mail_intake.models.message.json rename to docs/mcp/modules/mail_intake.models.message.json index 52131ee..c5d1973 100644 --- a/mcp_docs/modules/mail_intake.models.message.json +++ b/docs/mcp/modules/mail_intake.models.message.json @@ -18,25 +18,11 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.message.Optional", - "signature": "", - "docstring": null - }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.models.message.Dict", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.models.message.MailIntakeMessage", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { diff --git a/mcp_docs/modules/mail_intake.models.thread.json b/docs/mcp/modules/mail_intake.models.thread.json similarity index 91% rename from mcp_docs/modules/mail_intake.models.thread.json rename to docs/mcp/modules/mail_intake.models.thread.json index aa60d60..c91ea04 100644 --- a/mcp_docs/modules/mail_intake.models.thread.json +++ b/docs/mcp/modules/mail_intake.models.thread.json @@ -25,20 +25,6 @@ "signature": "", "docstring": null }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.models.thread.List", - "signature": "", - "docstring": null - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "mail_intake.models.thread.Set", - "signature": "", - "docstring": null - }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", @@ -115,7 +101,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -157,17 +143,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.parsers.body.json b/docs/mcp/modules/mail_intake.parsers.body.json similarity index 82% rename from mcp_docs/modules/mail_intake.parsers.body.json rename to docs/mcp/modules/mail_intake.parsers.body.json index cefc472..a8dffba 100644 --- a/mcp_docs/modules/mail_intake.parsers.body.json +++ b/docs/mcp/modules/mail_intake.parsers.body.json @@ -11,13 +11,6 @@ "signature": "", "docstring": null }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.body.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -25,13 +18,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.body.Optional", - "signature": "", - "docstring": null - }, "BeautifulSoup": { "name": "BeautifulSoup", "kind": "alias", diff --git a/mcp_docs/modules/mail_intake.parsers.headers.json b/docs/mcp/modules/mail_intake.parsers.headers.json similarity index 71% rename from mcp_docs/modules/mail_intake.parsers.headers.json rename to docs/mcp/modules/mail_intake.parsers.headers.json index 0b32806..e4f8230 100644 --- a/mcp_docs/modules/mail_intake.parsers.headers.json +++ b/docs/mcp/modules/mail_intake.parsers.headers.json @@ -4,46 +4,18 @@ "path": "mail_intake.parsers.headers", "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", "objects": { - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.headers.Dict", - "signature": "", - "docstring": null - }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.parsers.headers.List", - "signature": "", - "docstring": null - }, - "Tuple": { - "name": "Tuple", - "kind": "alias", - "path": "mail_intake.parsers.headers.Tuple", - "signature": "", - "docstring": null - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.headers.Optional", - "signature": "", - "docstring": null - }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", - "signature": "", + "signature": "", "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", + "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } diff --git a/mcp_docs/modules/mail_intake.parsers.json b/docs/mcp/modules/mail_intake.parsers.json similarity index 87% rename from mcp_docs/modules/mail_intake.parsers.json rename to docs/mcp/modules/mail_intake.parsers.json index 8c4c376..192b1f8 100644 --- a/mcp_docs/modules/mail_intake.parsers.json +++ b/docs/mcp/modules/mail_intake.parsers.json @@ -46,13 +46,6 @@ "signature": "", "docstring": null }, - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.body.Dict", - "signature": "", - "docstring": null - }, "Any": { "name": "Any", "kind": "alias", @@ -60,13 +53,6 @@ "signature": "", "docstring": null }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.body.Optional", - "signature": "", - "docstring": null - }, "BeautifulSoup": { "name": "BeautifulSoup", "kind": "alias", @@ -97,46 +83,18 @@ "signature": null, "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", "members": { - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.headers.Dict", - "signature": "", - "docstring": null - }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.parsers.headers.List", - "signature": "", - "docstring": null - }, - "Tuple": { - "name": "Tuple", - "kind": "alias", - "path": "mail_intake.parsers.headers.Tuple", - "signature": "", - "docstring": null - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.headers.Optional", - "signature": "", - "docstring": null - }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", - "signature": "", + "signature": "", "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", + "signature": "", "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } @@ -159,7 +117,7 @@ "name": "normalize_subject", "kind": "function", "path": "mail_intake.parsers.subject.normalize_subject", - "signature": "", + "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/mcp_docs/modules/mail_intake.parsers.subject.json b/docs/mcp/modules/mail_intake.parsers.subject.json similarity index 97% rename from mcp_docs/modules/mail_intake.parsers.subject.json rename to docs/mcp/modules/mail_intake.parsers.subject.json index 14c4cc7..b393fff 100644 --- a/mcp_docs/modules/mail_intake.parsers.subject.json +++ b/docs/mcp/modules/mail_intake.parsers.subject.json @@ -15,7 +15,7 @@ "name": "normalize_subject", "kind": "function", "path": "mail_intake.parsers.subject.normalize_subject", - "signature": "", + "signature": "", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/mcp_docs/nav.json b/docs/mcp/nav.json similarity index 100% rename from mcp_docs/nav.json rename to docs/mcp/nav.json diff --git a/mkdocs.yml b/mkdocs.yml index 36e786f..8fa7afa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,6 +63,7 @@ markdown_extensions: - pymdownx.tilde - pymdownx.mark site_name: mail_intake +docs_dir: docs/lib nav: - Home: index.md - Core API: