using doc forge

.drone.yml

@@ -23,50 +23,20 @@ steps:
     commands:
       - PACKAGE_NAME=$(grep -E '^name\s*=' pyproject.toml | head -1 | cut -d'"' -f2)
       - VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | cut -d'"' -f2)
+      - echo "🔍 Checking if $PACKAGE_NAME==$VERSION exists on $PIP_REPO_URL ..."
       - |
-        if [ "$DRONE_TAG" != "$VERSION" ]; then
-          echo "Tag '$DRONE_TAG' does not match pyproject version '$VERSION'; refusing to publish."
-          exit 1
-        fi
-      - echo "Checking if $PACKAGE_NAME==$VERSION exists on $PIP_REPO_URL ..."
-      - |
-        if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -qE "${PACKAGE_NAME}-${VERSION}(-|\.tar\.gz|\.whl)"; then
-          echo "$PACKAGE_NAME==$VERSION already exists; skipping build."
+        if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -q "$VERSION"; then
+          echo "✅ $PACKAGE_NAME==$VERSION already exists — skipping build."
           exit 78
         else
-          echo "New version detected: $PACKAGE_NAME==$VERSION"
+          echo "🆕 New version detected: $PACKAGE_NAME==$VERSION"
         fi
 
-  - name: quality-gate
-    image: python:3.13-slim
-    environment:
-      PIP_REPO_URL:
-        from_secret: PIP_REPO_URL
-      PIP_USERNAME:
-        from_secret: PIP_USERNAME
-      PIP_PASSWORD:
-        from_secret: PIP_PASSWORD
-    commands:
-      - pip install --upgrade pip build
-      - |
-        if [ -z "$PIP_REPO_URL" ] || [ -z "$PIP_USERNAME" ] || [ -z "$PIP_PASSWORD" ]; then
-          echo "PIP_REPO_URL / PIP_USERNAME / PIP_PASSWORD are not set" >&2
-          exit 1
-        fi
-      - AUTH_URL="https://$PIP_USERNAME:$PIP_PASSWORD@$(echo "$PIP_REPO_URL" | sed -E 's|^[a-zA-Z]+://||; s|/*$||')/simple"
-      - pip install --index-url "$AUTH_URL" --extra-index-url https://pypi.org/simple/ -U ".[dev]" "pydoclint>=0.9.1"
-      - echo "Running quality gate..."
-      - python -m black --check .
-      - python -m ruff check .
-      - python -m mypy
-      - pydoclint .
-      - python -m pytest
-
   - name: build-package
     image: python:3.13-slim
     commands:
       - pip install --upgrade pip build
-      - echo "Building Python package..."
+      - echo "📦 Building Python package..."
       - python -m build
       - ls -l dist
 
@@ -81,7 +51,7 @@ steps:
         from_secret: PIP_PASSWORD
     commands:
       - pip install --upgrade twine
-      - echo "Uploading to private PyPI at $PIP_REPO_URL ..."
+      - echo "🚀 Uploading to private PyPI at $PIP_REPO_URL ..."
       - |
         twine upload \
           --repository-url "$PIP_REPO_URL" \
@@ -128,31 +98,25 @@ steps:
         set -e
 
         PACKAGE_NAME=$(grep -E '^name\s*=' pyproject.toml | cut -d'"' -f2)
-        echo "Package: $PACKAGE_NAME"
+        echo "📦 Package: $PACKAGE_NAME"
 
         for TAG in $(git tag --sort=version:refname); do
           VERSION="$TAG"
-          echo "Version: $VERSION"
+          echo "🔁 Version: $VERSION"
 
           if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" \
-            "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -qE "${PACKAGE_NAME}-${VERSION}(-|\.tar\.gz|\.whl)"; then
-            echo "Exists, skipping"
+            "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -q "$VERSION"; then
+            echo "⏭️  Exists, skipping"
             continue
           fi
 
           git checkout --force "$TAG"
 
-          TAG_VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | cut -d'"' -f2)
-          if [ "$TAG" != "$TAG_VERSION" ]; then
-            echo "Tag $TAG != pyproject version $TAG_VERSION at that commit; skipping"
-            continue
-          fi
-
-          echo "Building $VERSION"
+          echo "🏗️  Building $VERSION"
           rm -rf dist
           python -m build
 
-          echo "Uploading $VERSION"
+          echo "⬆️  Uploading $VERSION"
           twine upload \
             --repository-url "$PIP_REPO_URL" \
             -u "$PIP_USERNAME" \

.gitignore

@@ -25,17 +25,10 @@ env/
 htmlcov/
 coverage.xml
 
-# Lint / type checking
-.mypy_cache/
-.ruff_cache/
-
 # Environment variables
 .env
 .env.local
 
-# Docs build artifacts
-site
-
 # OS
 .DS_Store
 Thumbs.db
@@ -45,6 +38,7 @@ Thumbs.db
 *.swo
 *~
 *.tmp
+site
 
 # Credentials
 client_secret_*.json

CHANGELOG.md

@@ -1,33 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.0.3] - 2026-10-17
-
-### Added
-- `py.typed` marker for PEP 561 type information.
-- Hand-written wiki, plus doc-forge-generated API reference under `docs/lib`
-  and MCP bundle under `docs/mcp` (per-kind MkDocs configs).
-- MIT `LICENSE`.
-
-### Changed
-- Adopted the standard Type A PyPI CI pipeline: a `tag == version` guard and a
-  quality gate (black, ruff, mypy, pydoclint, pytest).
-- Standardized `pyproject.toml` (canonical packaging, lint tool config, extras)
-  with a shared Google-style `[tool.pydoclint]` configuration.
-- Google-style (GSDFC) docstrings across the public API; legacy typing
-  modernised to match signatures.
-- `fetch_emails.py` debug script excluded from black/ruff scans.
-
-### Fixed
-- Regression test for immutable config models raises `AssertionError` instead
-  of a bare `assert False`.
-- Stub fixes for typed API surfaces.
-
-[Unreleased]: https://git.aetoskia.com/aetos/mail-intake/compare/0.0.3...HEAD
-[0.0.3]: https://git.aetoskia.com/aetos/mail-intake/compare/0.0.2...0.0.3

LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Aetoskia Platform
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

README.md

@@ -1,138 +0,0 @@
-# mail_intake
-
-# Summary
-
-Mail Intake — provider-agnostic, read-only email ingestion framework.
-
-Mail Intake is a **contract-first library** designed to ingest, parse, and
-normalize email data from external providers (such as Gmail) into clean,
-provider-agnostic domain models.
-
-The library is intentionally structured around clear layers, each exposed
-as a first-class module at the package root:
-
-- `adapters`: Provider-specific access (e.g., Gmail).
-- `auth`: Authentication providers and credential lifecycle management.
-- `credentials`: Credential persistence abstractions and implementations.
-- `parsers`: Extraction and normalization of message content.
-- `ingestion`: Orchestration and high-level ingestion workflows.
-- `models`: Canonical, provider-agnostic data representations.
-- `config`: Explicit global configuration.
-- `exceptions`: Library-defined error hierarchy.
-
-The package root acts as a **namespace**, not a facade. Consumers are
-expected to import functionality explicitly from the appropriate module.
-
----
-
-# Installation
-
-Install using pip:
-
-```bash
-pip install mail-intake
-```
-
-Or with Poetry:
-
-```bash
-poetry add mail-intake
-```
-
-Mail Intake is pure Python and has no runtime dependencies beyond those
-required by the selected provider (for example, Google APIs for Gmail).
-
----
-
-# Quick Start
-
-Minimal Gmail ingestion example (local development):
-
-```python
-from mail_intake.ingestion import MailIntakeReader
-from mail_intake.adapters import MailIntakeGmailAdapter
-from mail_intake.auth import MailIntakeGoogleAuth
-from mail_intake.credentials import PickleCredentialStore
-
-store = PickleCredentialStore(path="token.pickle")
-
-auth = MailIntakeGoogleAuth(
-    credentials_path="credentials.json",
-    store=store,
-    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
-)
-
-adapter = MailIntakeGmailAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
-
-for message in reader.iter_messages("from:recruiter@example.com"):
-    print(message.subject, message.from_email)
-```
-
-Iterating over threads:
-
-```python
-for thread in reader.iter_threads("subject:Interview"):
-    print(thread.normalized_subject, len(thread.messages))
-```
-
----
-
-# Architecture
-
-Mail Intake is designed to be extensible via **public contracts** exposed
-through its modules:
-
-- Users MAY implement their own mail adapters by subclassing
-  `adapters.MailIntakeAdapter`.
-- Users MAY implement their own authentication providers by subclassing
-  `auth.MailIntakeAuthProvider[T]`.
-- Users MAY implement their own credential persistence layers by implementing
-  `credentials.CredentialStore[T]`.
-
-Users SHOULD NOT subclass built-in adapter implementations. Built-in
-adapters (such as Gmail) are reference implementations and may change
-internally without notice.
-
-**Design Guarantees:**
-
-- Read-only access: no mutation of provider state.
-- Provider-agnostic domain models.
-- Explicit configuration and dependency injection.
-- No implicit global state or environment reads.
-- Deterministic, testable behavior.
-- Distributed-safe authentication design.
-
-Mail Intake favors correctness, clarity, and explicitness over convenience
-shortcuts.
-
-**Core Philosophy:**
-
-`Mail Intake` is built as a **contract-first ingestion pipeline**:
-
-1. **Layered Decoupling**: Adapters handle transport, Parsers handle format
-   normalization, and Ingestion orchestrates.
-2. **Provider Agnosticism**: Domain models and core logic never depend on
-   provider-specific (e.g., Gmail) API internals.
-3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring
-   side-effect-free ingestion.
-
----
-
-# Public API
-
-The supported public API consists of the following top-level modules:
-
-- `mail_intake.ingestion`
-- `mail_intake.adapters`
-- `mail_intake.auth`
-- `mail_intake.credentials`
-- `mail_intake.parsers`
-- `mail_intake.models`
-- `mail_intake.config`
-- `mail_intake.exceptions`
-
-Classes and functions should be imported explicitly from these modules.
-No individual symbols are re-exported at the package root.
-
----

docforge.nav.yml

@@ -1,32 +1,29 @@
-home: lib/index.md
+home: mail_intake/index.md
 groups:
   Core API:
-    - lib/ingestion/index.md
-    - lib/ingestion/reader.md
+    - mail_intake/ingestion/index.md
+    - mail_intake/ingestion/reader.md
   Domain Models:
-    - lib/models/index.md
-    - lib/models/message.md
-    - lib/models/thread.md
+    - mail_intake/models/index.md
+    - mail_intake/models/message.md
+    - mail_intake/models/thread.md
   Provider Adapters:
-    - lib/adapters/index.md
-    - lib/adapters/base.md
-    - lib/adapters/gmail.md
+    - mail_intake/adapters/index.md
+    - mail_intake/adapters/base.md
+    - mail_intake/adapters/gmail.md
   Authentication & Storage:
-    - lib/auth/index.md
-    - lib/auth/base.md
-    - lib/auth/google.md
-    - lib/credentials/index.md
-    - lib/credentials/store.md
-    - lib/credentials/pickle.md
-    - lib/credentials/redis.md
+    - mail_intake/auth/index.md
+    - mail_intake/auth/base.md
+    - mail_intake/auth/google.md
+    - mail_intake/credentials/index.md
+    - mail_intake/credentials/store.md
+    - mail_intake/credentials/pickle.md
+    - mail_intake/credentials/redis.md
   Normalization & Parsing:
-    - lib/parsers/index.md
-    - lib/parsers/body.md
-    - lib/parsers/headers.md
-    - lib/parsers/subject.md
+    - mail_intake/parsers/index.md
+    - mail_intake/parsers/body.md
+    - mail_intake/parsers/headers.md
+    - mail_intake/parsers/subject.md
   Configuration & Errors:
-    - lib/config.md
-    - lib/exceptions.md
-icon:
-  logo: material/inbox
-  repo: fontawesome/brands/github
+    - mail_intake/config.md
+    - mail_intake/exceptions.md

docs/mail_intake/index.md

@@ -1,3 +1,3 @@
-# mail_intake
+# Mail Intake
 
 ::: mail_intake

docs/mcp/modules/mail_intake.adapters.base.json

@@ -1,39 +0,0 @@
-{
-  "module": "mail_intake.adapters.base",
-  "content": {
-    "path": "mail_intake.adapters.base",
-    "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
-    "objects": {
-      "MailIntakeAdapter": {
-        "name": "MailIntakeAdapter",
-        "kind": "class",
-        "path": "mail_intake.adapters.base.MailIntakeAdapter",
-        "signature": null,
-        "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": "iter_message_refs(query: str) -> Iterator[dict[str, str]]",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-          },
-          "fetch_message": {
-            "name": "fetch_message",
-            "kind": "function",
-            "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
-            "signature": "fetch_message(message_id: str) -> dict[str, Any]",
-            "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": "fetch_thread(thread_id: str) -> dict[str, Any]",
-            "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."
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.adapters.gmail.json

@@ -1,99 +0,0 @@
-{
-  "module": "mail_intake.adapters.gmail",
-  "content": {
-    "path": "mail_intake.adapters.gmail",
-    "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.",
-    "objects": {
-      "MailIntakeAdapter": {
-        "name": "MailIntakeAdapter",
-        "kind": "class",
-        "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
-        "signature": null,
-        "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.gmail.MailIntakeAdapter.iter_message_refs",
-            "signature": "iter_message_refs(query: str)",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-          },
-          "fetch_message": {
-            "name": "fetch_message",
-            "kind": "function",
-            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
-            "signature": "fetch_message(message_id: str)",
-            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
-          },
-          "fetch_thread": {
-            "name": "fetch_thread",
-            "kind": "function",
-            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
-            "signature": "fetch_thread(thread_id: str)",
-            "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."
-          }
-        }
-      },
-      "MailIntakeAuthProvider": {
-        "name": "MailIntakeAuthProvider",
-        "kind": "class",
-        "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
-        "signature": null,
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-        "members": {
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
-            "signature": "get_credentials()",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-          }
-        }
-      },
-      "MailIntakeAdapterError": {
-        "name": "MailIntakeAdapterError",
-        "kind": "class",
-        "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
-        "signature": null,
-        "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": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')",
-        "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": {
-            "name": "service",
-            "kind": "attribute",
-            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
-            "signature": null,
-            "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail service cannot be initialized."
-          },
-          "iter_message_refs": {
-            "name": "iter_message_refs",
-            "kind": "function",
-            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
-            "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]",
-            "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": "fetch_message(message_id: str) -> dict[str, Any]",
-            "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": "fetch_thread(thread_id: str) -> dict[str, Any]",
-            "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."
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.adapters.json

@@ -1,214 +0,0 @@
-{
-  "module": "mail_intake.adapters",
-  "content": {
-    "path": "mail_intake.adapters",
-    "docstring": "# Summary\n\nMail provider adapter implementations for Mail Intake.\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n\n- Implement the `MailIntakeAdapter` interface.\n- Encapsulate all provider-specific APIs and semantics.\n- Perform read-only access to mail data.\n- Return provider-native payloads without interpretation.\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\n---\n\n# Public API\n\n- `MailIntakeAdapter`\n- `MailIntakeGmailAdapter`\n\n---",
-    "objects": {
-      "MailIntakeAdapter": {
-        "name": "MailIntakeAdapter",
-        "kind": "class",
-        "path": "mail_intake.adapters.MailIntakeAdapter",
-        "signature": null,
-        "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.MailIntakeAdapter.iter_message_refs",
-            "signature": "iter_message_refs(query: str)",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-          },
-          "fetch_message": {
-            "name": "fetch_message",
-            "kind": "function",
-            "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
-            "signature": "fetch_message(message_id: str)",
-            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
-          },
-          "fetch_thread": {
-            "name": "fetch_thread",
-            "kind": "function",
-            "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
-            "signature": "fetch_thread(thread_id: str)",
-            "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."
-          }
-        }
-      },
-      "MailIntakeGmailAdapter": {
-        "name": "MailIntakeGmailAdapter",
-        "kind": "class",
-        "path": "mail_intake.adapters.MailIntakeGmailAdapter",
-        "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')",
-        "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": {
-            "name": "service",
-            "kind": "attribute",
-            "path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
-            "signature": null,
-            "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail service cannot be initialized."
-          },
-          "iter_message_refs": {
-            "name": "iter_message_refs",
-            "kind": "function",
-            "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs",
-            "signature": "iter_message_refs(query: str)",
-            "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query (str):\n        Gmail search query string.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
-          },
-          "fetch_message": {
-            "name": "fetch_message",
-            "kind": "function",
-            "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
-            "signature": "fetch_message(message_id: str)",
-            "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id (str):\n        Gmail message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
-          },
-          "fetch_thread": {
-            "name": "fetch_thread",
-            "kind": "function",
-            "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
-            "signature": "fetch_thread(thread_id: str)",
-            "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."
-          }
-        }
-      },
-      "base": {
-        "name": "base",
-        "kind": "module",
-        "path": "mail_intake.adapters.base",
-        "signature": null,
-        "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
-        "members": {
-          "MailIntakeAdapter": {
-            "name": "MailIntakeAdapter",
-            "kind": "class",
-            "path": "mail_intake.adapters.base.MailIntakeAdapter",
-            "signature": null,
-            "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": "iter_message_refs(query: str) -> Iterator[dict[str, str]]",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-              },
-              "fetch_message": {
-                "name": "fetch_message",
-                "kind": "function",
-                "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
-                "signature": "fetch_message(message_id: str) -> dict[str, Any]",
-                "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": "fetch_thread(thread_id: str) -> dict[str, Any]",
-                "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."
-              }
-            }
-          }
-        }
-      },
-      "gmail": {
-        "name": "gmail",
-        "kind": "module",
-        "path": "mail_intake.adapters.gmail",
-        "signature": null,
-        "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.",
-        "members": {
-          "MailIntakeAdapter": {
-            "name": "MailIntakeAdapter",
-            "kind": "class",
-            "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
-            "signature": null,
-            "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.gmail.MailIntakeAdapter.iter_message_refs",
-                "signature": "iter_message_refs(query: str)",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-              },
-              "fetch_message": {
-                "name": "fetch_message",
-                "kind": "function",
-                "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
-                "signature": "fetch_message(message_id: str)",
-                "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
-              },
-              "fetch_thread": {
-                "name": "fetch_thread",
-                "kind": "function",
-                "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
-                "signature": "fetch_thread(thread_id: str)",
-                "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."
-              }
-            }
-          },
-          "MailIntakeAuthProvider": {
-            "name": "MailIntakeAuthProvider",
-            "kind": "class",
-            "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
-            "signature": null,
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-            "members": {
-              "get_credentials": {
-                "name": "get_credentials",
-                "kind": "function",
-                "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
-                "signature": "get_credentials()",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-              }
-            }
-          },
-          "MailIntakeAdapterError": {
-            "name": "MailIntakeAdapterError",
-            "kind": "class",
-            "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
-            "signature": null,
-            "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": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')",
-            "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": {
-                "name": "service",
-                "kind": "attribute",
-                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
-                "signature": null,
-                "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail service cannot be initialized."
-              },
-              "iter_message_refs": {
-                "name": "iter_message_refs",
-                "kind": "function",
-                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
-                "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]",
-                "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": "fetch_message(message_id: str) -> dict[str, Any]",
-                "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": "fetch_thread(thread_id: str) -> dict[str, Any]",
-                "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."
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.auth.base.json

@@ -1,32 +0,0 @@
-{
-  "module": "mail_intake.auth.base",
-  "content": {
-    "path": "mail_intake.auth.base",
-    "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
-    "objects": {
-      "T": {
-        "name": "T",
-        "kind": "attribute",
-        "path": "mail_intake.auth.base.T",
-        "signature": null,
-        "docstring": null
-      },
-      "MailIntakeAuthProvider": {
-        "name": "MailIntakeAuthProvider",
-        "kind": "class",
-        "path": "mail_intake.auth.base.MailIntakeAuthProvider",
-        "signature": null,
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-        "members": {
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
-            "signature": "get_credentials() -> T",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.auth.google.json

@@ -1,99 +0,0 @@
-{
-  "module": "mail_intake.auth.google",
-  "content": {
-    "path": "mail_intake.auth.google",
-    "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.",
-    "objects": {
-      "MailIntakeAuthProvider": {
-        "name": "MailIntakeAuthProvider",
-        "kind": "class",
-        "path": "mail_intake.auth.google.MailIntakeAuthProvider",
-        "signature": null,
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-        "members": {
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
-            "signature": "get_credentials()",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-          }
-        }
-      },
-      "CredentialStore": {
-        "name": "CredentialStore",
-        "kind": "class",
-        "path": "mail_intake.auth.google.CredentialStore",
-        "signature": null,
-        "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.auth.google.CredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.auth.google.CredentialStore.save",
-            "signature": "save(credentials: T)",
-            "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.auth.google.CredentialStore.clear",
-            "signature": "clear()",
-            "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"
-          }
-        }
-      },
-      "MailIntakeAuthError": {
-        "name": "MailIntakeAuthError",
-        "kind": "class",
-        "path": "mail_intake.auth.google.MailIntakeAuthError",
-        "signature": null,
-        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
-      },
-      "MailIntakeGoogleAuth": {
-        "name": "MailIntakeGoogleAuth",
-        "kind": "class",
-        "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
-        "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])",
-        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
-        "members": {
-          "credentials_path": {
-            "name": "credentials_path",
-            "kind": "attribute",
-            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path",
-            "signature": null,
-            "docstring": null
-          },
-          "store": {
-            "name": "store",
-            "kind": "attribute",
-            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.store",
-            "signature": null,
-            "docstring": null
-          },
-          "scopes": {
-            "name": "scopes",
-            "kind": "attribute",
-            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.scopes",
-            "signature": null,
-            "docstring": null
-          },
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
-            "signature": "get_credentials() -> Any",
-            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.auth.json

@@ -1,193 +0,0 @@
-{
-  "module": "mail_intake.auth",
-  "content": {
-    "path": "mail_intake.auth",
-    "docstring": "# Summary\n\nAuthentication provider implementations for Mail Intake.\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n\n- A stable, provider-agnostic authentication contract.\n- Concrete authentication providers for supported platforms.\n\nAuthentication providers:\n\n- Are responsible for credential acquisition and lifecycle management.\n- Are intentionally decoupled from adapter logic.\n- May be extended by users to support additional providers.\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.\n\n---\n\n# Public API\n\n- `MailIntakeAuthProvider`\n- `MailIntakeGoogleAuth`\n\n---",
-    "objects": {
-      "MailIntakeAuthProvider": {
-        "name": "MailIntakeAuthProvider",
-        "kind": "class",
-        "path": "mail_intake.auth.MailIntakeAuthProvider",
-        "signature": null,
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-        "members": {
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials",
-            "signature": "get_credentials()",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-          }
-        }
-      },
-      "MailIntakeGoogleAuth": {
-        "name": "MailIntakeGoogleAuth",
-        "kind": "class",
-        "path": "mail_intake.auth.MailIntakeGoogleAuth",
-        "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])",
-        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
-        "members": {
-          "credentials_path": {
-            "name": "credentials_path",
-            "kind": "attribute",
-            "path": "mail_intake.auth.MailIntakeGoogleAuth.credentials_path",
-            "signature": null,
-            "docstring": null
-          },
-          "store": {
-            "name": "store",
-            "kind": "attribute",
-            "path": "mail_intake.auth.MailIntakeGoogleAuth.store",
-            "signature": null,
-            "docstring": null
-          },
-          "scopes": {
-            "name": "scopes",
-            "kind": "attribute",
-            "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes",
-            "signature": null,
-            "docstring": null
-          },
-          "get_credentials": {
-            "name": "get_credentials",
-            "kind": "function",
-            "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
-            "signature": "get_credentials()",
-            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
-          }
-        }
-      },
-      "base": {
-        "name": "base",
-        "kind": "module",
-        "path": "mail_intake.auth.base",
-        "signature": null,
-        "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
-        "members": {
-          "T": {
-            "name": "T",
-            "kind": "attribute",
-            "path": "mail_intake.auth.base.T",
-            "signature": null,
-            "docstring": null
-          },
-          "MailIntakeAuthProvider": {
-            "name": "MailIntakeAuthProvider",
-            "kind": "class",
-            "path": "mail_intake.auth.base.MailIntakeAuthProvider",
-            "signature": null,
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-            "members": {
-              "get_credentials": {
-                "name": "get_credentials",
-                "kind": "function",
-                "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
-                "signature": "get_credentials() -> T",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-              }
-            }
-          }
-        }
-      },
-      "google": {
-        "name": "google",
-        "kind": "module",
-        "path": "mail_intake.auth.google",
-        "signature": null,
-        "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.",
-        "members": {
-          "MailIntakeAuthProvider": {
-            "name": "MailIntakeAuthProvider",
-            "kind": "class",
-            "path": "mail_intake.auth.google.MailIntakeAuthProvider",
-            "signature": null,
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
-            "members": {
-              "get_credentials": {
-                "name": "get_credentials",
-                "kind": "function",
-                "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
-                "signature": "get_credentials()",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
-              }
-            }
-          },
-          "CredentialStore": {
-            "name": "CredentialStore",
-            "kind": "class",
-            "path": "mail_intake.auth.google.CredentialStore",
-            "signature": null,
-            "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.auth.google.CredentialStore.load",
-                "signature": "load()",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.auth.google.CredentialStore.save",
-                "signature": "save(credentials: T)",
-                "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.auth.google.CredentialStore.clear",
-                "signature": "clear()",
-                "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"
-              }
-            }
-          },
-          "MailIntakeAuthError": {
-            "name": "MailIntakeAuthError",
-            "kind": "class",
-            "path": "mail_intake.auth.google.MailIntakeAuthError",
-            "signature": null,
-            "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
-          },
-          "MailIntakeGoogleAuth": {
-            "name": "MailIntakeGoogleAuth",
-            "kind": "class",
-            "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
-            "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])",
-            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
-            "members": {
-              "credentials_path": {
-                "name": "credentials_path",
-                "kind": "attribute",
-                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path",
-                "signature": null,
-                "docstring": null
-              },
-              "store": {
-                "name": "store",
-                "kind": "attribute",
-                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.store",
-                "signature": null,
-                "docstring": null
-              },
-              "scopes": {
-                "name": "scopes",
-                "kind": "attribute",
-                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.scopes",
-                "signature": null,
-                "docstring": null
-              },
-              "get_credentials": {
-                "name": "get_credentials",
-                "kind": "function",
-                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
-                "signature": "get_credentials() -> Any",
-                "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.credentials.json

@@ -1,381 +0,0 @@
-{
-  "module": "mail_intake.credentials",
-  "content": {
-    "path": "mail_intake.credentials",
-    "docstring": "# Summary\n\nCredential persistence interfaces and implementations for Mail Intake.\n\nThis package defines the abstractions and concrete implementations used\nto persist authentication credentials across Mail Intake components.\n\nThe credential persistence layer is intentionally decoupled from\nauthentication logic. Authentication providers are responsible for\ncredential acquisition, validation, and refresh, while implementations\nwithin this package are responsible solely for storage and retrieval.\n\nThe package provides:\n\n- A generic `CredentialStore` abstraction defining the persistence contract.\n- Local filesystem–based storage for development and single-node use.\n- Distributed, Redis-backed storage for production and scaled deployments.\n\nCredential lifecycle management, interpretation, and security policy\ndecisions remain the responsibility of authentication providers.\n\n---\n\n# Public API\n\n- `CredentialStore`\n- `PickleCredentialStore`\n- `RedisCredentialStore`\n\n---",
-    "objects": {
-      "CredentialStore": {
-        "name": "CredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.CredentialStore",
-        "signature": null,
-        "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.CredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.CredentialStore.save",
-            "signature": "save(credentials: T)",
-            "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.CredentialStore.clear",
-            "signature": "clear()",
-            "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"
-          }
-        }
-      },
-      "PickleCredentialStore": {
-        "name": "PickleCredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.PickleCredentialStore",
-        "signature": "PickleCredentialStore(path: str)",
-        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
-        "members": {
-          "path": {
-            "name": "path",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.PickleCredentialStore.path",
-            "signature": null,
-            "docstring": null
-          },
-          "load": {
-            "name": "load",
-            "kind": "function",
-            "path": "mail_intake.credentials.PickleCredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.PickleCredentialStore.save",
-            "signature": "save(credentials: T)",
-            "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
-          },
-          "clear": {
-            "name": "clear",
-            "kind": "function",
-            "path": "mail_intake.credentials.PickleCredentialStore.clear",
-            "signature": "clear()",
-            "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
-          }
-        }
-      },
-      "RedisCredentialStore": {
-        "name": "RedisCredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.RedisCredentialStore",
-        "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)",
-        "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
-        "members": {
-          "redis": {
-            "name": "redis",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.RedisCredentialStore.redis",
-            "signature": null,
-            "docstring": null
-          },
-          "key": {
-            "name": "key",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.RedisCredentialStore.key",
-            "signature": null,
-            "docstring": null
-          },
-          "serialize": {
-            "name": "serialize",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.RedisCredentialStore.serialize",
-            "signature": null,
-            "docstring": null
-          },
-          "deserialize": {
-            "name": "deserialize",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.RedisCredentialStore.deserialize",
-            "signature": null,
-            "docstring": null
-          },
-          "ttl_seconds": {
-            "name": "ttl_seconds",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.RedisCredentialStore.ttl_seconds",
-            "signature": null,
-            "docstring": null
-          },
-          "load": {
-            "name": "load",
-            "kind": "function",
-            "path": "mail_intake.credentials.RedisCredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load credentials from Redis.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.RedisCredentialStore.save",
-            "signature": "save(credentials: T)",
-            "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
-          },
-          "clear": {
-            "name": "clear",
-            "kind": "function",
-            "path": "mail_intake.credentials.RedisCredentialStore.clear",
-            "signature": "clear()",
-            "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
-          }
-        }
-      },
-      "pickle": {
-        "name": "pickle",
-        "kind": "module",
-        "path": "mail_intake.credentials.pickle",
-        "signature": null,
-        "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
-        "members": {
-          "CredentialStore": {
-            "name": "CredentialStore",
-            "kind": "class",
-            "path": "mail_intake.credentials.pickle.CredentialStore",
-            "signature": null,
-            "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.pickle.CredentialStore.load",
-                "signature": "load()",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.credentials.pickle.CredentialStore.save",
-                "signature": "save(credentials: T)",
-                "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.pickle.CredentialStore.clear",
-                "signature": "clear()",
-                "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"
-              }
-            }
-          },
-          "T": {
-            "name": "T",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.pickle.T",
-            "signature": null,
-            "docstring": null
-          },
-          "PickleCredentialStore": {
-            "name": "PickleCredentialStore",
-            "kind": "class",
-            "path": "mail_intake.credentials.pickle.PickleCredentialStore",
-            "signature": "PickleCredentialStore(path: str)",
-            "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
-            "members": {
-              "path": {
-                "name": "path",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.pickle.PickleCredentialStore.path",
-                "signature": null,
-                "docstring": null
-              },
-              "load": {
-                "name": "load",
-                "kind": "function",
-                "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
-                "signature": "load() -> T | None",
-                "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
-                "signature": "save(credentials: T) -> None",
-                "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
-              },
-              "clear": {
-                "name": "clear",
-                "kind": "function",
-                "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
-                "signature": "clear() -> None",
-                "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
-              }
-            }
-          }
-        }
-      },
-      "redis": {
-        "name": "redis",
-        "kind": "module",
-        "path": "mail_intake.credentials.redis",
-        "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": {
-          "CredentialStore": {
-            "name": "CredentialStore",
-            "kind": "class",
-            "path": "mail_intake.credentials.redis.CredentialStore",
-            "signature": null,
-            "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.redis.CredentialStore.load",
-                "signature": "load()",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.credentials.redis.CredentialStore.save",
-                "signature": "save(credentials: T)",
-                "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.redis.CredentialStore.clear",
-                "signature": "clear()",
-                "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"
-              }
-            }
-          },
-          "T": {
-            "name": "T",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.T",
-            "signature": null,
-            "docstring": null
-          },
-          "RedisCredentialStore": {
-            "name": "RedisCredentialStore",
-            "kind": "class",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore",
-            "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)",
-            "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
-            "members": {
-              "redis": {
-                "name": "redis",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.redis",
-                "signature": null,
-                "docstring": null
-              },
-              "key": {
-                "name": "key",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.key",
-                "signature": null,
-                "docstring": null
-              },
-              "serialize": {
-                "name": "serialize",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.serialize",
-                "signature": null,
-                "docstring": null
-              },
-              "deserialize": {
-                "name": "deserialize",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.deserialize",
-                "signature": null,
-                "docstring": null
-              },
-              "ttl_seconds": {
-                "name": "ttl_seconds",
-                "kind": "attribute",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.ttl_seconds",
-                "signature": null,
-                "docstring": null
-              },
-              "load": {
-                "name": "load",
-                "kind": "function",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
-                "signature": "load() -> T | None",
-                "docstring": "Load credentials from Redis.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.save",
-                "signature": "save(credentials: T) -> None",
-                "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
-              },
-              "clear": {
-                "name": "clear",
-                "kind": "function",
-                "path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
-                "signature": "clear() -> None",
-                "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
-              }
-            }
-          }
-        }
-      },
-      "store": {
-        "name": "store",
-        "kind": "module",
-        "path": "mail_intake.credentials.store",
-        "signature": null,
-        "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
-        "members": {
-          "T": {
-            "name": "T",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.store.T",
-            "signature": null,
-            "docstring": null
-          },
-          "CredentialStore": {
-            "name": "CredentialStore",
-            "kind": "class",
-            "path": "mail_intake.credentials.store.CredentialStore",
-            "signature": null,
-            "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": "load() -> T | None",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-              },
-              "save": {
-                "name": "save",
-                "kind": "function",
-                "path": "mail_intake.credentials.store.CredentialStore.save",
-                "signature": "save(credentials: T) -> None",
-                "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": "clear() -> None",
-                "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"
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.credentials.pickle.json

@@ -1,83 +0,0 @@
-{
-  "module": "mail_intake.credentials.pickle",
-  "content": {
-    "path": "mail_intake.credentials.pickle",
-    "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
-    "objects": {
-      "CredentialStore": {
-        "name": "CredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.pickle.CredentialStore",
-        "signature": null,
-        "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.pickle.CredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.pickle.CredentialStore.save",
-            "signature": "save(credentials: T)",
-            "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.pickle.CredentialStore.clear",
-            "signature": "clear()",
-            "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"
-          }
-        }
-      },
-      "T": {
-        "name": "T",
-        "kind": "attribute",
-        "path": "mail_intake.credentials.pickle.T",
-        "signature": null,
-        "docstring": null
-      },
-      "PickleCredentialStore": {
-        "name": "PickleCredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.pickle.PickleCredentialStore",
-        "signature": "PickleCredentialStore(path: str)",
-        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
-        "members": {
-          "path": {
-            "name": "path",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.pickle.PickleCredentialStore.path",
-            "signature": null,
-            "docstring": null
-          },
-          "load": {
-            "name": "load",
-            "kind": "function",
-            "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
-            "signature": "load() -> T | None",
-            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
-            "signature": "save(credentials: T) -> None",
-            "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
-          },
-          "clear": {
-            "name": "clear",
-            "kind": "function",
-            "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
-            "signature": "clear() -> None",
-            "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.credentials.redis.json

@@ -1,111 +0,0 @@
-{
-  "module": "mail_intake.credentials.redis",
-  "content": {
-    "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": {
-      "CredentialStore": {
-        "name": "CredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.redis.CredentialStore",
-        "signature": null,
-        "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.redis.CredentialStore.load",
-            "signature": "load()",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.redis.CredentialStore.save",
-            "signature": "save(credentials: T)",
-            "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.redis.CredentialStore.clear",
-            "signature": "clear()",
-            "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"
-          }
-        }
-      },
-      "T": {
-        "name": "T",
-        "kind": "attribute",
-        "path": "mail_intake.credentials.redis.T",
-        "signature": null,
-        "docstring": null
-      },
-      "RedisCredentialStore": {
-        "name": "RedisCredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.redis.RedisCredentialStore",
-        "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)",
-        "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
-        "members": {
-          "redis": {
-            "name": "redis",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.redis",
-            "signature": null,
-            "docstring": null
-          },
-          "key": {
-            "name": "key",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.key",
-            "signature": null,
-            "docstring": null
-          },
-          "serialize": {
-            "name": "serialize",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.serialize",
-            "signature": null,
-            "docstring": null
-          },
-          "deserialize": {
-            "name": "deserialize",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.deserialize",
-            "signature": null,
-            "docstring": null
-          },
-          "ttl_seconds": {
-            "name": "ttl_seconds",
-            "kind": "attribute",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.ttl_seconds",
-            "signature": null,
-            "docstring": null
-          },
-          "load": {
-            "name": "load",
-            "kind": "function",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
-            "signature": "load() -> T | None",
-            "docstring": "Load credentials from Redis.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.save",
-            "signature": "save(credentials: T) -> None",
-            "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
-          },
-          "clear": {
-            "name": "clear",
-            "kind": "function",
-            "path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
-            "signature": "clear() -> None",
-            "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.credentials.store.json

@@ -1,46 +0,0 @@
-{
-  "module": "mail_intake.credentials.store",
-  "content": {
-    "path": "mail_intake.credentials.store",
-    "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
-    "objects": {
-      "T": {
-        "name": "T",
-        "kind": "attribute",
-        "path": "mail_intake.credentials.store.T",
-        "signature": null,
-        "docstring": null
-      },
-      "CredentialStore": {
-        "name": "CredentialStore",
-        "kind": "class",
-        "path": "mail_intake.credentials.store.CredentialStore",
-        "signature": null,
-        "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": "load() -> T | None",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    T | None:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
-          },
-          "save": {
-            "name": "save",
-            "kind": "function",
-            "path": "mail_intake.credentials.store.CredentialStore.save",
-            "signature": "save(credentials: T) -> None",
-            "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": "clear() -> None",
-            "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"
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.exceptions.json

@@ -1,37 +0,0 @@
-{
-  "module": "mail_intake.exceptions",
-  "content": {
-    "path": "mail_intake.exceptions",
-    "docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.",
-    "objects": {
-      "MailIntakeError": {
-        "name": "MailIntakeError",
-        "kind": "class",
-        "path": "mail_intake.exceptions.MailIntakeError",
-        "signature": null,
-        "docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n    **Guarantees:**\n\n        - This is the root of the Mail Intake exception hierarchy\n        - All errors raised by the library must derive from this class\n        - Consumers should generally catch this type when handling library-level failures"
-      },
-      "MailIntakeAuthError": {
-        "name": "MailIntakeAuthError",
-        "kind": "class",
-        "path": "mail_intake.exceptions.MailIntakeAuthError",
-        "signature": null,
-        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
-      },
-      "MailIntakeAdapterError": {
-        "name": "MailIntakeAdapterError",
-        "kind": "class",
-        "path": "mail_intake.exceptions.MailIntakeAdapterError",
-        "signature": null,
-        "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
-      },
-      "MailIntakeParsingError": {
-        "name": "MailIntakeParsingError",
-        "kind": "class",
-        "path": "mail_intake.exceptions.MailIntakeParsingError",
-        "signature": null,
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.ingestion.json

@@ -1,252 +0,0 @@
-{
-  "module": "mail_intake.ingestion",
-  "content": {
-    "path": "mail_intake.ingestion",
-    "docstring": "# Summary\n\nMail ingestion orchestration for Mail Intake.\n\nThis package contains **high-level ingestion components** responsible for\ncoordinating mail retrieval, parsing, normalization, and model construction.\n\nIt represents the **top of the ingestion pipeline** and is intended to be the\nprimary interaction surface for library consumers.\n\nComponents in this package:\n\n- Are provider-agnostic.\n- Depend only on adapter and parser contracts.\n- Contain no provider-specific API logic.\n- Expose read-only ingestion workflows.\n\nConsumers are expected to construct a mail adapter and pass it to the\ningestion layer to begin processing messages and threads.\n\n---\n\n# Public API\n\n- `MailIntakeReader`\n\n---",
-    "objects": {
-      "MailIntakeReader": {
-        "name": "MailIntakeReader",
-        "kind": "class",
-        "path": "mail_intake.ingestion.MailIntakeReader",
-        "signature": "MailIntakeReader(adapter: MailIntakeAdapter)",
-        "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.MailIntakeReader.iter_messages",
-            "signature": "iter_messages(query: str)",
-            "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.MailIntakeReader.iter_threads",
-            "signature": "iter_threads(query: str)",
-            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[MailIntakeThread]:\n        An iterator over `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
-          }
-        }
-      },
-      "reader": {
-        "name": "reader",
-        "kind": "module",
-        "path": "mail_intake.ingestion.reader",
-        "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": {
-          "MailIntakeAdapter": {
-            "name": "MailIntakeAdapter",
-            "kind": "class",
-            "path": "mail_intake.ingestion.reader.MailIntakeAdapter",
-            "signature": null,
-            "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.ingestion.reader.MailIntakeAdapter.iter_message_refs",
-                "signature": "iter_message_refs(query: str)",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-              },
-              "fetch_message": {
-                "name": "fetch_message",
-                "kind": "function",
-                "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
-                "signature": "fetch_message(message_id: str)",
-                "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
-              },
-              "fetch_thread": {
-                "name": "fetch_thread",
-                "kind": "function",
-                "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
-                "signature": "fetch_thread(thread_id: str)",
-                "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."
-              }
-            }
-          },
-          "MailIntakeParsingError": {
-            "name": "MailIntakeParsingError",
-            "kind": "class",
-            "path": "mail_intake.ingestion.reader.MailIntakeParsingError",
-            "signature": null,
-            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
-          },
-          "MailIntakeMessage": {
-            "name": "MailIntakeMessage",
-            "kind": "class",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage",
-            "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])",
-            "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": {
-                "name": "message_id",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id",
-                "signature": null,
-                "docstring": "Provider-specific message identifier."
-              },
-              "thread_id": {
-                "name": "thread_id",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id",
-                "signature": null,
-                "docstring": "Provider-specific thread identifier to which this message belongs."
-              },
-              "timestamp": {
-                "name": "timestamp",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp",
-                "signature": null,
-                "docstring": "Message timestamp as a timezone-naive UTC datetime."
-              },
-              "from_email": {
-                "name": "from_email",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_email",
-                "signature": null,
-                "docstring": "Sender email address."
-              },
-              "from_name": {
-                "name": "from_name",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name",
-                "signature": null,
-                "docstring": "Optional human-readable sender name."
-              },
-              "subject": {
-                "name": "subject",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject",
-                "signature": null,
-                "docstring": "Raw subject line of the message."
-              },
-              "body_text": {
-                "name": "body_text",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text",
-                "signature": null,
-                "docstring": "Extracted plain-text body content of the message."
-              },
-              "snippet": {
-                "name": "snippet",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet",
-                "signature": null,
-                "docstring": "Short provider-supplied preview snippet of the message."
-              },
-              "raw_headers": {
-                "name": "raw_headers",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeMessage.raw_headers",
-                "signature": null,
-                "docstring": "Normalized mapping of message headers (header name → value)."
-              }
-            }
-          },
-          "MailIntakeThread": {
-            "name": "MailIntakeThread",
-            "kind": "class",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread",
-            "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)",
-            "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": {
-                "name": "thread_id",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.thread_id",
-                "signature": null,
-                "docstring": "Provider-specific thread identifier."
-              },
-              "normalized_subject": {
-                "name": "normalized_subject",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject",
-                "signature": null,
-                "docstring": "Normalized subject line used to group related messages."
-              },
-              "participants": {
-                "name": "participants",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.participants",
-                "signature": null,
-                "docstring": "Set of unique participant email addresses observed in the thread."
-              },
-              "messages": {
-                "name": "messages",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.messages",
-                "signature": null,
-                "docstring": "Ordered list of messages belonging to this thread."
-              },
-              "last_activity_at": {
-                "name": "last_activity_at",
-                "kind": "attribute",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.last_activity_at",
-                "signature": null,
-                "docstring": "Timestamp of the most recent message in the thread."
-              },
-              "add_message": {
-                "name": "add_message",
-                "kind": "function",
-                "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message",
-                "signature": "add_message(message: MailIntakeMessage)",
-                "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."
-              }
-            }
-          },
-          "extract_body": {
-            "name": "extract_body",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.extract_body",
-            "signature": "extract_body(payload: dict[str, Any])",
-            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
-          },
-          "extract_sender": {
-            "name": "extract_sender",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.extract_sender",
-            "signature": "extract_sender(headers: dict[str, str])",
-            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    tuple[str, str | None]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
-          },
-          "parse_headers": {
-            "name": "parse_headers",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.parse_headers",
-            "signature": "parse_headers(raw_headers: list[dict[str, str]])",
-            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (list[dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
-          },
-          "normalize_subject": {
-            "name": "normalize_subject",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.normalize_subject",
-            "signature": "normalize_subject(subject: str)",
-            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
-          },
-          "MailIntakeReader": {
-            "name": "MailIntakeReader",
-            "kind": "class",
-            "path": "mail_intake.ingestion.reader.MailIntakeReader",
-            "signature": "MailIntakeReader(adapter: MailIntakeAdapter)",
-            "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": "iter_messages(query: str) -> Iterator[MailIntakeMessage]",
-                "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": "iter_threads(query: str) -> Iterator[MailIntakeThread]",
-                "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[MailIntakeThread]:\n        An iterator over `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.ingestion.reader.json

@@ -1,220 +0,0 @@
-{
-  "module": "mail_intake.ingestion.reader",
-  "content": {
-    "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": {
-      "MailIntakeAdapter": {
-        "name": "MailIntakeAdapter",
-        "kind": "class",
-        "path": "mail_intake.ingestion.reader.MailIntakeAdapter",
-        "signature": null,
-        "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.ingestion.reader.MailIntakeAdapter.iter_message_refs",
-            "signature": "iter_message_refs(query: str)",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[dict[str, str]]:\n        An iterator over lightweight message reference dictionaries.\n\nYields:\n    dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
-          },
-          "fetch_message": {
-            "name": "fetch_message",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
-            "signature": "fetch_message(message_id: str)",
-            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
-          },
-          "fetch_thread": {
-            "name": "fetch_thread",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
-            "signature": "fetch_thread(thread_id: str)",
-            "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."
-          }
-        }
-      },
-      "MailIntakeParsingError": {
-        "name": "MailIntakeParsingError",
-        "kind": "class",
-        "path": "mail_intake.ingestion.reader.MailIntakeParsingError",
-        "signature": null,
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
-      },
-      "MailIntakeMessage": {
-        "name": "MailIntakeMessage",
-        "kind": "class",
-        "path": "mail_intake.ingestion.reader.MailIntakeMessage",
-        "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])",
-        "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": {
-            "name": "message_id",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id",
-            "signature": null,
-            "docstring": "Provider-specific message identifier."
-          },
-          "thread_id": {
-            "name": "thread_id",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id",
-            "signature": null,
-            "docstring": "Provider-specific thread identifier to which this message belongs."
-          },
-          "timestamp": {
-            "name": "timestamp",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp",
-            "signature": null,
-            "docstring": "Message timestamp as a timezone-naive UTC datetime."
-          },
-          "from_email": {
-            "name": "from_email",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_email",
-            "signature": null,
-            "docstring": "Sender email address."
-          },
-          "from_name": {
-            "name": "from_name",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name",
-            "signature": null,
-            "docstring": "Optional human-readable sender name."
-          },
-          "subject": {
-            "name": "subject",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject",
-            "signature": null,
-            "docstring": "Raw subject line of the message."
-          },
-          "body_text": {
-            "name": "body_text",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text",
-            "signature": null,
-            "docstring": "Extracted plain-text body content of the message."
-          },
-          "snippet": {
-            "name": "snippet",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet",
-            "signature": null,
-            "docstring": "Short provider-supplied preview snippet of the message."
-          },
-          "raw_headers": {
-            "name": "raw_headers",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeMessage.raw_headers",
-            "signature": null,
-            "docstring": "Normalized mapping of message headers (header name → value)."
-          }
-        }
-      },
-      "MailIntakeThread": {
-        "name": "MailIntakeThread",
-        "kind": "class",
-        "path": "mail_intake.ingestion.reader.MailIntakeThread",
-        "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)",
-        "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": {
-            "name": "thread_id",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.thread_id",
-            "signature": null,
-            "docstring": "Provider-specific thread identifier."
-          },
-          "normalized_subject": {
-            "name": "normalized_subject",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject",
-            "signature": null,
-            "docstring": "Normalized subject line used to group related messages."
-          },
-          "participants": {
-            "name": "participants",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.participants",
-            "signature": null,
-            "docstring": "Set of unique participant email addresses observed in the thread."
-          },
-          "messages": {
-            "name": "messages",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.messages",
-            "signature": null,
-            "docstring": "Ordered list of messages belonging to this thread."
-          },
-          "last_activity_at": {
-            "name": "last_activity_at",
-            "kind": "attribute",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.last_activity_at",
-            "signature": null,
-            "docstring": "Timestamp of the most recent message in the thread."
-          },
-          "add_message": {
-            "name": "add_message",
-            "kind": "function",
-            "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message",
-            "signature": "add_message(message: MailIntakeMessage)",
-            "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."
-          }
-        }
-      },
-      "extract_body": {
-        "name": "extract_body",
-        "kind": "function",
-        "path": "mail_intake.ingestion.reader.extract_body",
-        "signature": "extract_body(payload: dict[str, Any])",
-        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
-      },
-      "extract_sender": {
-        "name": "extract_sender",
-        "kind": "function",
-        "path": "mail_intake.ingestion.reader.extract_sender",
-        "signature": "extract_sender(headers: dict[str, str])",
-        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    tuple[str, str | None]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
-      },
-      "parse_headers": {
-        "name": "parse_headers",
-        "kind": "function",
-        "path": "mail_intake.ingestion.reader.parse_headers",
-        "signature": "parse_headers(raw_headers: list[dict[str, str]])",
-        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (list[dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
-      },
-      "normalize_subject": {
-        "name": "normalize_subject",
-        "kind": "function",
-        "path": "mail_intake.ingestion.reader.normalize_subject",
-        "signature": "normalize_subject(subject: str)",
-        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
-      },
-      "MailIntakeReader": {
-        "name": "MailIntakeReader",
-        "kind": "class",
-        "path": "mail_intake.ingestion.reader.MailIntakeReader",
-        "signature": "MailIntakeReader(adapter: MailIntakeAdapter)",
-        "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": "iter_messages(query: str) -> Iterator[MailIntakeMessage]",
-            "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": "iter_threads(query: str) -> Iterator[MailIntakeThread]",
-            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nReturns:\n    Iterator[MailIntakeThread]:\n        An iterator over `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
-          }
-        }
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.parsers.body.json

@@ -1,23 +0,0 @@
-{
-  "module": "mail_intake.parsers.body",
-  "content": {
-    "path": "mail_intake.parsers.body",
-    "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
-    "objects": {
-      "MailIntakeParsingError": {
-        "name": "MailIntakeParsingError",
-        "kind": "class",
-        "path": "mail_intake.parsers.body.MailIntakeParsingError",
-        "signature": null,
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
-      },
-      "extract_body": {
-        "name": "extract_body",
-        "kind": "function",
-        "path": "mail_intake.parsers.body.extract_body",
-        "signature": "extract_body(payload: dict[str, Any]) -> str",
-        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.parsers.headers.json

@@ -1,23 +0,0 @@
-{
-  "module": "mail_intake.parsers.headers",
-  "content": {
-    "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": {
-      "parse_headers": {
-        "name": "parse_headers",
-        "kind": "function",
-        "path": "mail_intake.parsers.headers.parse_headers",
-        "signature": "parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]",
-        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (list[dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
-      },
-      "extract_sender": {
-        "name": "extract_sender",
-        "kind": "function",
-        "path": "mail_intake.parsers.headers.extract_sender",
-        "signature": "extract_sender(headers: dict[str, str]) -> tuple[str, str | None]",
-        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    tuple[str, str | None]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
-      }
-    }
-  }
-}

docs/mcp/modules/mail_intake.parsers.json

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

docs/mcp/modules/mail_intake.parsers.subject.json

@@ -1,16 +0,0 @@
-{
-  "module": "mail_intake.parsers.subject",
-  "content": {
-    "path": "mail_intake.parsers.subject",
-    "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
-    "objects": {
-      "normalize_subject": {
-        "name": "normalize_subject",
-        "kind": "function",
-        "path": "mail_intake.parsers.subject.normalize_subject",
-        "signature": "normalize_subject(subject: str) -> str",
-        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
-      }
-    }
-  }
-}

docs/mcp/nav.json

@@ -1,90 +0,0 @@
-[
-  {
-    "module": "mail_intake",
-    "resource": "docs://modules/mail_intake"
-  },
-  {
-    "module": "mail_intake.adapters",
-    "resource": "docs://modules/mail_intake.adapters"
-  },
-  {
-    "module": "mail_intake.adapters.base",
-    "resource": "docs://modules/mail_intake.adapters.base"
-  },
-  {
-    "module": "mail_intake.adapters.gmail",
-    "resource": "docs://modules/mail_intake.adapters.gmail"
-  },
-  {
-    "module": "mail_intake.auth",
-    "resource": "docs://modules/mail_intake.auth"
-  },
-  {
-    "module": "mail_intake.auth.base",
-    "resource": "docs://modules/mail_intake.auth.base"
-  },
-  {
-    "module": "mail_intake.auth.google",
-    "resource": "docs://modules/mail_intake.auth.google"
-  },
-  {
-    "module": "mail_intake.config",
-    "resource": "docs://modules/mail_intake.config"
-  },
-  {
-    "module": "mail_intake.credentials",
-    "resource": "docs://modules/mail_intake.credentials"
-  },
-  {
-    "module": "mail_intake.credentials.pickle",
-    "resource": "docs://modules/mail_intake.credentials.pickle"
-  },
-  {
-    "module": "mail_intake.credentials.redis",
-    "resource": "docs://modules/mail_intake.credentials.redis"
-  },
-  {
-    "module": "mail_intake.credentials.store",
-    "resource": "docs://modules/mail_intake.credentials.store"
-  },
-  {
-    "module": "mail_intake.exceptions",
-    "resource": "docs://modules/mail_intake.exceptions"
-  },
-  {
-    "module": "mail_intake.ingestion",
-    "resource": "docs://modules/mail_intake.ingestion"
-  },
-  {
-    "module": "mail_intake.ingestion.reader",
-    "resource": "docs://modules/mail_intake.ingestion.reader"
-  },
-  {
-    "module": "mail_intake.models",
-    "resource": "docs://modules/mail_intake.models"
-  },
-  {
-    "module": "mail_intake.models.message",
-    "resource": "docs://modules/mail_intake.models.message"
-  },
-  {
-    "module": "mail_intake.models.thread",
-    "resource": "docs://modules/mail_intake.models.thread"
-  },
-  {
-    "module": "mail_intake.parsers",
-    "resource": "docs://modules/mail_intake.parsers"
-  },
-  {
-    "module": "mail_intake.parsers.body",
-    "resource": "docs://modules/mail_intake.parsers.body"
-  },
-  {
-    "module": "mail_intake.parsers.headers",
-    "resource": "docs://modules/mail_intake.parsers.headers"
-  },
-  {
-    "module": "mail_intake.parsers.subject",
-    "resource": "docs://modules/mail_intake.parsers.subject"
-  }
-]

docs/mkdocs.lib.yml

@@ -1,100 +0,0 @@
-theme:
-  name: material
-  palette:
-  - scheme: slate
-    primary: deep purple
-    accent: cyan
-  font:
-    text: Inter
-    code: JetBrains Mono
-  features:
-  - navigation.sections
-  - navigation.expand
-  - navigation.top
-  - navigation.instant
-  - navigation.tracking
-  - navigation.indexes
-  - content.code.copy
-  - content.code.annotate
-  - content.tabs.link
-  - content.action.edit
-  - search.highlight
-  - search.share
-  - search.suggest
-  icon:
-    logo: material/inbox
-    repo: fontawesome/brands/github
-markdown_extensions:
-- pymdownx.superfences
-- pymdownx.inlinehilite
-- pymdownx.snippets
-- admonition
-- pymdownx.details
-- pymdownx.highlight:
-    linenums: true
-    anchor_linenums: true
-    line_spans: __span
-    pygments_lang_class: true
-- pymdownx.tabbed:
-    alternate_style: true
-- pymdownx.tasklist:
-    custom_checkbox: true
-- tables
-- footnotes
-- pymdownx.caret
-- pymdownx.tilde
-- pymdownx.mark
-extra_css:
-- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
-plugins:
-- search
-- mkdocstrings:
-    handlers:
-      python:
-        paths:
-        - ..
-        options:
-          docstring_style: google
-          show_source: false
-          show_signature_annotations: true
-          separate_signature: true
-          merge_init_into_class: true
-          inherited_members: true
-          annotations_path: brief
-          show_root_heading: true
-          group_by_category: true
-          show_category_heading: true
-          show_object_full_path: false
-          show_symbol_type_heading: true
-site_name: mail_intake
-docs_dir: lib
-site_dir: ../site/lib
-nav:
-- Home: index.md
-- Core API:
-  - ingestion/index.md
-  - ingestion/reader.md
-- Domain Models:
-  - models/index.md
-  - models/message.md
-  - models/thread.md
-- Provider Adapters:
-  - adapters/index.md
-  - adapters/base.md
-  - adapters/gmail.md
-- Authentication & Storage:
-  - auth/index.md
-  - auth/base.md
-  - auth/google.md
-  - credentials/index.md
-  - credentials/store.md
-  - credentials/pickle.md
-  - credentials/redis.md
-- Normalization & Parsing:
-  - parsers/index.md
-  - parsers/body.md
-  - parsers/headers.md
-  - parsers/subject.md
-- Configuration & Errors:
-  - config.md
-  - exceptions.md

docs/mkdocs.wiki.yml

@@ -1,70 +0,0 @@
-site_name: Mail Intake Documentation
-docs_dir: wiki
-site_dir: ../site/wiki
-
-nav:
-- Home: index.md
-- Overview: 01_overview.md
-- How to Use: 02_how_to_use.md
-- Extending Mail Intake: 03_extending.md
-- Development: 04_development.md
-
-theme:
-  name: material
-  palette:
-    scheme: slate
-    primary: blue grey
-    accent: teal
-  font:
-    text: Roboto
-    code: JetBrains Mono
-  features:
-  - navigation.sections
-  - navigation.expand
-  - navigation.top
-  - navigation.instant
-  - navigation.tracking
-  - navigation.indexes
-  - content.code.copy
-  - content.code.annotate
-  - content.tabs.link
-  - content.action.edit
-  - search.highlight
-  - search.share
-  - search.suggest
-  - navigation.tabs
-  - toc.integrate
-  - header.autohide
-  - announce.dismiss
-  - footer.social
-  - content.code.select
-  - content.code.line_numbers
-  - content.tooltips
-  icon:
-    logo: material/inbox
-    repo: fontawesome/brands/github
-markdown_extensions:
-- pymdownx.superfences
-- pymdownx.inlinehilite
-- pymdownx.snippets
-- admonition
-- pymdownx.details
-- pymdownx.highlight:
-    linenums: true
-    anchor_linenums: true
-    line_spans: __span
-    pygments_lang_class: true
-- pymdownx.tabbed:
-    alternate_style: true
-- pymdownx.tasklist:
-    custom_checkbox: true
-- tables
-- footnotes
-- pymdownx.caret
-- pymdownx.tilde
-- pymdownx.mark
-extra_css:
-- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
-plugins:
-- search
-- docforge-linkfix

docs/wiki/01_overview.md

@@ -1,91 +0,0 @@
-# 🧱 Overview
-
-Mail Intake is a **contract-first ingestion pipeline**. Adapters handle
-transport to a provider, parsers normalize provider payloads, and the reader
-orchestrates the whole flow into canonical domain models.
-
----
-
-## 🏗️ Architecture
-
-```text
-                 ┌─────────────────────────────────────────┐
-                 │  External Provider (e.g. Gmail API)     │
-                 └─────────────────────┬───────────────────┘
-                                      │
-                    ┌─────────────────▼──────────────────┐
-                    │  MailIntakeAdapter (transport)      │   provider API calls
-                    └─────────────────┬──────────────────┘
-                                      │  provider-native payloads
-                    ┌─────────────────▼──────────────────┐
-                    │  Parsers (normalization)           │   headers, body, subject
-                    └─────────────────┬──────────────────┘
-                                      │  composed
-                    ┌─────────────────▼──────────────────┐
-                    │  MailIntakeReader (orchestration)  │   iter_messages / iter_threads
-                    └─────────────────┬──────────────────┘
-                                      │
-                    ┌─────────────────▼──────────────────┐
-                    │  MailIntakeMessage / Thread        │   canonical domain models
-                    └────────────────────────────────────┘
-```
-
-Layers:
-
-1. **Adapters** (`mail_intake.adapters`) — provider-specific, read-only
-   transport. Return provider-native payloads; never interpret them.
-2. **Auth** (`mail_intake.auth`) — credential acquisition and lifecycle
-   management, decoupled from adapters.
-3. **Credentials** (`mail_intake.credentials`) — persistence of auth tokens;
-   `PickleCredentialStore` locally, `RedisCredentialStore` for production.
-4. **Parsers** (`mail_intake.parsers`) — extract headers, body text, sender,
-   and normalized subjects from provider payloads.
-5. **Ingestion** (`mail_intake.ingestion`) — `MailIntakeReader` wires an
-   adapter + parsers into iterators over canonical models.
-6. **Models** (`mail_intake.models`) — provider-agnostic `MailIntakeMessage`
-   and `MailIntakeThread`.
-
----
-
-## 📦 Domain models
-
-`MailIntakeMessage`:
-
-| Field | Type | Meaning |
-|---|---|---|
-| `message_id` | `str` | Provider message id |
-| `thread_id` | `str` | Conversation thread id |
-| `timestamp` | `datetime` | Message timestamp |
-| `from_email` | `str` | Sender email |
-| `from_name` | `str \| None` | Sender display name |
-| `subject` | `str` | Message subject |
-| `body_text` | `str` | Extracted plain-text body |
-| `snippet` | `str` | Provider snippet |
-| `raw_headers` | `dict[str, str]` | Unmodified headers |
-
-`MailIntakeThread`:
-
-| Field | Type | Meaning |
-|---|---|---|
-| `thread_id` | `str` | Conversation id |
-| `normalized_subject` | `str` | Normalized subject (threads share one) |
-| `participants` | `set[str]` | Distinct senders |
-| `messages` | `list[MailIntakeMessage]` | Ordered messages |
-| `last_activity_at` | `datetime \| None` | Latest message time |
-
----
-
-## 🔒 Design guarantees
-
-- Read-only access — no mutation of provider state.
-- Provider-agnostic domain models.
-- Explicit configuration and dependency injection (no implicit env reads).
-- Extensible via public contracts; built-in adapters are reference
-  implementations and may change internally.
-
----
-
-## 📚 Read Next
-
-- [How to Use](02_how_to_use.md) — the Gmail ingestion flow.
-- [Extending Mail Intake](03_extending.md) — custom adapters and stores.

docs/wiki/02_how_to_use.md

@@ -1,105 +0,0 @@
-# 🖥️ How to Use
-
-This page walks through authenticating, ingesting, and parsing mail with the
-built-in Gmail support.
-
----
-
-## 🔐 Authentication
-
-Create a credential store and an auth provider:
-
-```python
-from mail_intake.auth import MailIntakeGoogleAuth
-from mail_intake.credentials import PickleCredentialStore, RedisCredentialStore
-
-store = PickleCredentialStore(path="token.pickle")          # local dev
-
-auth = MailIntakeGoogleAuth(
-    credentials_path="credentials.json",                    # your OAuth client file
-    store=store,
-    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
-)
-```
-
-> OAuth credentials come from the Google Cloud Console and are provided via
-> file paths — never hard-code tokens or secrets in source. Once authorized,
-> the token is persisted by the credential store and refreshed automatically.
-
-For distributed deployments, use Redis instead of pickle:
-
-```python
-store = RedisCredentialStore(redis_client=redis_client)     # production
-```
-
----
-
-## 📥 Ingesting messages
-
-Build an adapter and a reader, then iterate:
-
-```python
-from mail_intake.ingestion import MailIntakeReader
-from mail_intake.adapters import MailIntakeGmailAdapter
-
-adapter = MailIntakeGmailAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
-
-for message in reader.iter_messages("from:recruiter@example.com"):
-    print(message.subject, message.from_email, message.timestamp)
-```
-
-Access the full model:
-
-```python
-message.message_id    # provider id
-message.thread_id
-message.body_text     # plain-text body
-message.raw_headers   # unmodified headers dict
-```
-
----
-
-## 🔖 Ingesting threads
-
-```python
-for thread in reader.iter_threads("subject:Interview"):
-    print(thread.normalized_subject)
-    print(thread.participants)
-    print(len(thread.messages))
-    print(thread.last_activity_at)
-```
-
-`MailIntakeThread` aggregates its messages, participants, and last activity.
-
----
-
-## 🧪 Parsers
-
-Parsers normalize provider payloads and are used by the reader internally.
-They are also importable on their own:
-
-```python
-from mail_intake.parsers import extract_body, parse_headers, normalize_subject
-```
-
-- `extract_body(...)` — plain-text body extraction.
-- `parse_headers(...)` — structured header parsing.
-- `extract_sender(...)` — sender email/name extraction.
-- `normalize_subject(...)` — subject normalization for threading.
-
----
-
-## ✅ Checklist
-
-1. Provide OAuth credentials via a file path and a credential store.
-2. Build the `MailIntakeGoogleAuth` provider with the Gmail read-only scope.
-3. Wrap the adapter in a `MailIntakeReader`.
-4. Consume `iter_messages` / `iter_threads`; never call provider APIs directly.
-
----
-
-## 📚 Read Next
-
-- [Overview](01_overview.md) — layers and domain models.
-- [Extending Mail Intake](03_extending.md) — custom providers and stores.

docs/wiki/03_extending.md

@@ -1,106 +0,0 @@
-# 🧩 Extending Mail Intake
-
-Mail Intake is designed to be extended through its **public contracts**.
-Implement your own adapter, auth provider, or credential store to support a
-new provider or storage backend.
-
----
-
-## 📬 Custom adapters
-
-Subclass `MailIntakeAdapter` to integrate a new provider. Adapters perform
-read-only transport and return provider-native payloads:
-
-```python
-from mail_intake.adapters import MailIntakeAdapter
-
-class ExchangeAdapter(MailIntakeAdapter):
-    def __init__(self, auth_provider):
-        self._auth = auth_provider
-
-    def fetch_messages(self, query):
-        # call the provider API, return native payloads
-        ...
-
-    def fetch_threads(self, query):
-        ...
-```
-
-> **Do not** subclass built-in adapters like `MailIntakeGmailAdapter` — they
-> are reference implementations and may change internally without notice.
-
----
-
-## 🔐 Custom auth providers
-
-Subclass `MailIntakeAuthProvider[T]` to own a different credential flow:
-
-```python
-from mail_intake.auth import MailIntakeAuthProvider
-
-class ExchangeAuth(MailIntakeAuthProvider[exchange_credentials]):
-    def get_credentials(self):
-        return self._store.load()
-
-    def refresh(self):
-        ...
-```
-
-Auth providers remain decoupled from adapter logic — they only manage
-credentials.
-
----
-
-## 🗄️ Custom credential stores
-
-Implement the `CredentialStore[T]` contract for a new persistence backend:
-
-```python
-from mail_intake.credentials import CredentialStore
-
-class S3CredentialStore(CredentialStore):
-    def save(self, credentials):
-        ...
-
-    def load(self):
-        ...
-
-    def delete(self):
-        ...
-```
-
-The store abstraction keeps tokens out of config and rotates safely.
-
----
-
-## 🧪 Wiring a custom backend
-
-```python
-from mail_intake.ingestion import MailIntakeReader
-
-auth = ExchangeAuth(store=S3CredentialStore(...))
-adapter = ExchangeAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
-
-for message in reader.iter_messages("query"):
-    print(message.subject)
-```
-
-The reader only depends on the adapter contract, so the rest of the pipeline
-keeps working unchanged.
-
----
-
-## ✅ Extension checklist
-
-1. Implement the **public contract** — never subclass built-in adapters.
-2. Keep transport in the adapter, parsing in parsers, auth in the provider.
-3. Return the provider-native payload and let parsers normalize it.
-4. Inject dependencies explicitly — no global state or env reads.
-
----
-
-## 📚 Read Next
-
-- [How to Use](02_how_to_use.md) — the built-in Gmail flow.
-- [Development](04_development.md) — running tests and docs.

docs/wiki/04_development.md

@@ -1,88 +0,0 @@
-# 🛠️ Development
-
-Working on `mail-intake` itself.
-
----
-
-## 📂 Repository layout
-
-| Path | Purpose |
-|---|---|
-| `mail_intake/` | The library package (adapters, auth, credentials, parsers, ingestion, models) |
-| `mail_intake/*.pyi` | Type stubs kept in sync with implementations |
-| `tests/` | Unit and integration tests (mock transports, no live mail) |
-| `docs/lib/` | Generated library reference (docforge, flat layout) |
-| `docs/mcp/` | Machine-readable bundle served by the MCP server |
-| `docs/wiki/` | This hand-written wiki |
-
----
-
-## 🔧 Setup
-
-```bash
-python -m venv .venv
-.venv/Scripts/pip install -e ".[dev]"
-```
-
-> OAuth credential files (`credentials*.json`, `token.pickle`,
-> `client_secret_*.json`) are gitignored — keep them out of the repository.
-
----
-
-## 🧪 Tests
-
-Run the suite (no network or live Gmail required):
-
-```bash
-.venv/Scripts/pytest
-```
-
-Coverage spans ingestion flows, credential stores, parsers, and auth against
-mock providers.
-
----
-
-## ✅ Quality gates
-
-The CI quality gate runs, matching the Drone pipeline:
-
-```bash
-.venv/Scripts/black --check .
-.venv/Scripts/ruff check .
-.venv/Scripts/mypy
-.venv/Scripts/pytest
-```
-
----
-
-## 📝 Building documentation (docforge)
-
-The site is generated by [`docforge`](https://git.aetoskia.com/aetos/doc-forge)
-and served per kind under `site/{kind}`:
-
-```bash
-doc-forge build \
-  --mkdocs --mcp --wiki \
-  --module-is-source --module mail_intake \
-  --site-name "Mail Intake"
-```
-
-- `--module-is-source` renders the flat `docs/lib/` layout (no nesting under
-  `mail_intake/`), matching `docforge.nav.yml` and `docs/mkdocs.lib.yml`.
-- `--mcp` regenerates the structured bundle in `docs/mcp/`.
-- `--wiki` builds this wiki.
-
-Preview locally:
-
-```bash
-doc-forge serve --lib
-doc-forge serve --wiki
-doc-forge serve --mcp
-```
-
----
-
-## 📚 Read Next
-
-- [Extending Mail Intake](03_extending.md) — custom adapters and stores.
-- [Overview](01_overview.md) — the core architecture.

docs/wiki/index.md

@@ -1,71 +0,0 @@
-# 📬 Mail Intake — Provider-Agnostic Email Ingestion
-
-`Mail Intake` is a contract-first, read-only email ingestion framework. It
-pulls mail from external providers (such as Gmail), parses and normalizes it
-into clean, provider-agnostic domain models — ready to persist, index, or
-analyze downstream.
-
-> **Doc model:** this wiki is written for humans — how‑to guides and extension
-> recipes. The authoritative API contracts live in the code (GSDFC docstrings)
-> and the machine‑readable bundle under `docs/mcp/`.
-
----
-
-## 🚀 Key Features
-
-* 📬 **Read-only ingestion** — never mutates provider state
-* 🧩 **Contract-first layers** — adapters, parsers, and readers separated
-* ✉️ **Provider-agnostic models** — `MailIntakeMessage` / `MailIntakeThread`
-  have no provider internals
-* 🔐 **Extensible auth** — pluggable auth providers and credential stores
-  (pickle for dev, Redis for production)
-* 🧪 **Deterministic & testable** — no implicit global state or env reads
-* 📊 **Gmail support** — reference adapter built on the official Google APIs
-
----
-
-## ⚡ Quick Start
-
-```python
-from mail_intake.ingestion import MailIntakeReader
-from mail_intake.adapters import MailIntakeGmailAdapter
-from mail_intake.auth import MailIntakeGoogleAuth
-from mail_intake.credentials import PickleCredentialStore
-
-store = PickleCredentialStore(path="token.pickle")
-
-auth = MailIntakeGoogleAuth(
-    credentials_path="credentials.json",
-    store=store,
-    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
-)
-
-adapter = MailIntakeGmailAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
-
-for message in reader.iter_messages("from:recruiter@example.com"):
-    print(message.subject, message.from_email)
-```
-
----
-
-## 📁 Documentation Structure
-
-| Section | What you'll find |
-|---|---|
-| [Overview](01_overview.md) | Layers, domain models, and design guarantees |
-| [How to Use](02_how_to_use.md) | Gmail ingestion, parsing, and credential stores |
-| [Extending Mail Intake](03_extending.md) | Custom adapters, auth providers, stores |
-| [Development](04_development.md) | Setup, tests, and regenerating docs |
-
----
-
-## 🔗 Related Resources
-
-* **Source Code:** [Gitea Repository](https://git.aetoskia.com/aetos/mail-intake)
-* **Internal PyPI:** [pip.aetoskia.com/simple/mail-intake](https://pip.aetoskia.com/simple/mail-intake)
-* **CI:** Builds and publishes tagged releases, gated on black / ruff / mypy / pytest.
-
----
-
-© Aetoskia Internal — `mail-intake` 0.0.2

fetch_emails.py

@@ -1,22 +0,0 @@
-from mail_intake.ingestion import MailIntakeReader
-from mail_intake.adapters import MailIntakeGmailAdapter
-from mail_intake.auth import MailIntakeGoogleAuth
-from mail_intake.credentials.pickle import PickleCredentialStore
-
-store = PickleCredentialStore(path="token.pickle")
-
-auth = MailIntakeGoogleAuth(
-    credentials_path="credentials.json",
-    store=store,
-    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
-)
-auth.get_credentials()
-
-adapter = MailIntakeGmailAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
-
-for message in reader.iter_messages("from:roshnisingh009@gmail.com"):
-    print(message.subject, message.from_email)
-    break
-
-from pdb import set_trace;set_trace()

mail_intake/__init__.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Mail Intake — provider-agnostic, read-only email ingestion framework.
 
 Mail Intake is a **contract-first library** designed to ingest, parse, and
@@ -10,133 +8,136 @@ provider-agnostic domain models.
 The library is intentionally structured around clear layers, each exposed
 as a first-class module at the package root:
 
-- `adapters`: Provider-specific access (e.g., Gmail).
-- `auth`: Authentication providers and credential lifecycle management.
-- `credentials`: Credential persistence abstractions and implementations.
-- `parsers`: Extraction and normalization of message content.
-- `ingestion`: Orchestration and high-level ingestion workflows.
-- `models`: Canonical, provider-agnostic data representations.
-- `config`: Explicit global configuration.
-- `exceptions`: Library-defined error hierarchy.
+- adapters: provider-specific access (e.g. Gmail)
+- auth: authentication providers and credential lifecycle management
+- credentials: credential persistence abstractions and implementations
+- parsers: extraction and normalization of message content
+- ingestion: orchestration and high-level ingestion workflows
+- models: canonical, provider-agnostic data representations
+- config: explicit global configuration
+- exceptions: library-defined error hierarchy
 
 The package root acts as a **namespace**, not a facade. Consumers are
 expected to import functionality explicitly from the appropriate module.
 
----
-
-# Installation
+----------------------------------------------------------------------
+Installation
+----------------------------------------------------------------------
 
 Install using pip:
 
-```bash
-pip install mail-intake
-```
+    pip install mail-intake
 
 Or with Poetry:
 
-```bash
-poetry add mail-intake
-```
+    poetry add mail-intake
 
 Mail Intake is pure Python and has no runtime dependencies beyond those
 required by the selected provider (for example, Google APIs for Gmail).
 
----
-
-# Quick Start
+----------------------------------------------------------------------
+Basic Usage
+----------------------------------------------------------------------
 
 Minimal Gmail ingestion example (local development):
 
-```python
-from mail_intake.ingestion import MailIntakeReader
-from mail_intake.adapters import MailIntakeGmailAdapter
-from mail_intake.auth import MailIntakeGoogleAuth
-from mail_intake.credentials import PickleCredentialStore
+    from mail_intake.ingestion import MailIntakeReader
+    from mail_intake.adapters import MailIntakeGmailAdapter
+    from mail_intake.auth import MailIntakeGoogleAuth
+    from mail_intake.credentials import PickleCredentialStore
 
-store = PickleCredentialStore(path="token.pickle")
+    store = PickleCredentialStore(path="token.pickle")
 
-auth = MailIntakeGoogleAuth(
-    credentials_path="credentials.json",
-    store=store,
-    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
-)
+    auth = MailIntakeGoogleAuth(
+        credentials_path="credentials.json",
+        store=store,
+        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+    )
 
-adapter = MailIntakeGmailAdapter(auth_provider=auth)
-reader = MailIntakeReader(adapter)
+    adapter = MailIntakeGmailAdapter(auth_provider=auth)
+    reader = MailIntakeReader(adapter)
 
-for message in reader.iter_messages("from:recruiter@example.com"):
-    print(message.subject, message.from_email)
-```
+    for message in reader.iter_messages("from:recruiter@example.com"):
+        print(message.subject, message.from_email)
 
 Iterating over threads:
 
-```python
-for thread in reader.iter_threads("subject:Interview"):
-    print(thread.normalized_subject, len(thread.messages))
-```
+    for thread in reader.iter_threads("subject:Interview"):
+        print(thread.normalized_subject, len(thread.messages))
 
----
-
-# Architecture
+----------------------------------------------------------------------
+Extensibility Model
+----------------------------------------------------------------------
 
 Mail Intake is designed to be extensible via **public contracts** exposed
 through its modules:
 
 - Users MAY implement their own mail adapters by subclassing
-  `adapters.MailIntakeAdapter`.
+  ``adapters.MailIntakeAdapter``
 - Users MAY implement their own authentication providers by subclassing
-  `auth.MailIntakeAuthProvider[T]`.
-- Users MAY implement their own credential persistence layers by implementing
-  `credentials.CredentialStore[T]`.
+  ``auth.MailIntakeAuthProvider[T]``
+- Users MAY implement their own credential persistence layers by
+  implementing ``credentials.CredentialStore[T]``
 
 Users SHOULD NOT subclass built-in adapter implementations. Built-in
 adapters (such as Gmail) are reference implementations and may change
 internally without notice.
 
-**Design Guarantees:**
-
-- Read-only access: no mutation of provider state.
-- Provider-agnostic domain models.
-- Explicit configuration and dependency injection.
-- No implicit global state or environment reads.
-- Deterministic, testable behavior.
-- Distributed-safe authentication design.
-
-Mail Intake favors correctness, clarity, and explicitness over convenience
-shortcuts.
-
-**Core Philosophy:**
-
-`Mail Intake` is built as a **contract-first ingestion pipeline**:
-
-1. **Layered Decoupling**: Adapters handle transport, Parsers handle format
-   normalization, and Ingestion orchestrates.
-2. **Provider Agnosticism**: Domain models and core logic never depend on
-   provider-specific (e.g., Gmail) API internals.
-3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring
-   side-effect-free ingestion.
-
----
-
-# Public API
+----------------------------------------------------------------------
+Public API Surface
+----------------------------------------------------------------------
 
 The supported public API consists of the following top-level modules:
 
-- `mail_intake.ingestion`
-- `mail_intake.adapters`
-- `mail_intake.auth`
-- `mail_intake.credentials`
-- `mail_intake.parsers`
-- `mail_intake.models`
-- `mail_intake.config`
-- `mail_intake.exceptions`
+- mail_intake.ingestion
+- mail_intake.adapters
+- mail_intake.auth
+- mail_intake.credentials
+- mail_intake.parsers
+- mail_intake.models
+- mail_intake.config
+- mail_intake.exceptions
 
 Classes and functions should be imported explicitly from these modules.
 No individual symbols are re-exported at the package root.
 
----
+----------------------------------------------------------------------
+Design Guarantees
+----------------------------------------------------------------------
+
+- Read-only access: no mutation of provider state
+- Provider-agnostic domain models
+- Explicit configuration and dependency injection
+- No implicit global state or environment reads
+- Deterministic, testable behavior
+- Distributed-safe authentication design
+
+Mail Intake favors correctness, clarity, and explicitness over convenience
+shortcuts.
+
+## Core Philosophy
+
+`Mail Intake` is built as a **contract-first ingestion pipeline**:
+
+1. **Layered Decoupling**: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
+2. **Provider Agnosticism**: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
+3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
+
+## Documentation Design
+
+Follow these "AI-Native" docstring principles across the codebase:
+
+### For Humans
+- **Namespace Clarity**: Always specify which module a class or function belongs to.
+- **Contract Explanations**: Use the `adapters` and `auth` base classes to explain extension requirements.
+
+### For LLMs
+- **Dotted Paths**: Use full dotted paths in docstrings to help agents link concepts across modules.
+- **Typed Interfaces**: Provide `.pyi` stubs for every public module to ensure perfect context for AI coding tools.
+- **Canonical Exceptions**: Always use `: description` pairs in `Raises` blocks to enable structured error analysis.
 """
 
+
 from . import ingestion
 from . import adapters
 from . import auth

mail_intake/__init__.pyi

@@ -1,4 +1,10 @@
-from . import adapters, auth, config, credentials, exceptions, ingestion, models
+from . import ingestion
+from . import adapters
+from . import auth
+from . import credentials
+from . import models
+from . import config
+from . import exceptions
 
 __all__ = [
     "ingestion",

mail_intake/adapters/__init__.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Mail provider adapter implementations for Mail Intake.
 
 This package contains **adapter-layer implementations** responsible for
@@ -8,24 +6,17 @@ interfacing with external mail providers and exposing a normalized,
 provider-agnostic contract to the rest of the system.
 
 Adapters in this package:
-
-- Implement the `MailIntakeAdapter` interface.
-- Encapsulate all provider-specific APIs and semantics.
-- Perform read-only access to mail data.
-- Return provider-native payloads without interpretation.
+- Implement the `MailIntakeAdapter` interface
+- Encapsulate all provider-specific APIs and semantics
+- Perform read-only access to mail data
+- Return provider-native payloads without interpretation
 
 Provider-specific logic **must not leak** outside of adapter implementations.
 All parsings, normalizations, and transformations must be handled by downstream
 components.
 
----
-
-# Public API
-
-- `MailIntakeAdapter`
-- `MailIntakeGmailAdapter`
-
----
+Public adapters exported from this package are considered the supported
+integration surface for mail providers.
 """
 
 from .base import MailIntakeAdapter

mail_intake/adapters/base.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Mail provider adapter contracts for Mail Intake.
 
 This module defines the **provider-agnostic adapter interface** used for
@@ -12,87 +10,67 @@ types or semantics should leak beyond implementations of this interface.
 """
 
 from abc import ABC, abstractmethod
-from collections.abc import Iterator
-from typing import Any
+from typing import Iterator, Dict, Any
 
 
 class MailIntakeAdapter(ABC):
     """
     Base adapter interface for mail providers.
 
-    Notes:
-        **Guarantees:**
+    This interface defines the minimal contract required to:
+    - Discover messages matching a query
+    - Retrieve full message payloads
+    - Retrieve full thread payloads
 
-            - Discover messages matching a query.
-            - Retrieve full message payloads.
-            - Retrieve full thread payloads.
-
-        **Lifecycle:**
-
-            - Adapters are intentionally read-only and must not mutate provider state.
+    Adapters are intentionally read-only and must not mutate provider state.
     """
 
     @abstractmethod
-    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
+    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
         """
         Iterate over lightweight message references matching a query.
 
-        Args:
-            query (str):
-                Provider-specific query string used to filter messages.
+        Implementations must yield dictionaries containing at least:
+        - ``message_id``: Provider-specific message identifier
+        - ``thread_id``: Provider-specific thread identifier
 
-        Returns:
-            Iterator[dict[str, str]]:
-                An iterator over lightweight message reference dictionaries.
+        Args:
+            query: Provider-specific query string used to filter messages.
 
         Yields:
-            dict[str, str]:
-                Dictionaries containing message and thread identifiers.
+            Dictionaries containing message and thread identifiers.
 
-        Notes:
-            **Guarantees:**
-
-                - Implementations must yield dictionaries containing at least
-                  `message_id` and `thread_id`.
-
-        Example:
-            Typical yield:
-
-            ```python
+        Example yield:
             {
                 "message_id": "...",
                 "thread_id": "..."
             }
-            ```
         """
         raise NotImplementedError
 
     @abstractmethod
-    def fetch_message(self, message_id: str) -> dict[str, Any]:
+    def fetch_message(self, message_id: str) -> Dict[str, Any]:
         """
         Fetch a full raw message by message identifier.
 
         Args:
-            message_id (str):
-                Provider-specific message identifier.
+            message_id: Provider-specific message identifier.
 
         Returns:
-            dict[str, Any]:
-                Provider-native message payload (e.g., Gmail message JSON structure).
+            Provider-native message payload
+            (e.g., Gmail message JSON structure).
         """
         raise NotImplementedError
 
     @abstractmethod
-    def fetch_thread(self, thread_id: str) -> dict[str, Any]:
+    def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
         """
         Fetch a full raw thread by thread identifier.
 
         Args:
-            thread_id (str):
-                Provider-specific thread identifier.
+            thread_id: Provider-specific thread identifier.
 
         Returns:
-            dict[str, Any]:
-                Provider-native thread payload.
+            Provider-native thread payload.
         """
         raise NotImplementedError

mail_intake/adapters/base.pyi

@@ -1,11 +1,10 @@
 from abc import ABC, abstractmethod
-from collections.abc import Iterator
-from typing import Any
+from typing import Iterator, Dict, Any
 
 class MailIntakeAdapter(ABC):
     @abstractmethod
-    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
+    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
     @abstractmethod
-    def fetch_message(self, message_id: str) -> dict[str, Any]: ...
+    def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
     @abstractmethod
-    def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...
+    def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...

mail_intake/adapters/gmail.py

@@ -1,29 +1,25 @@
 """
-# Summary
-
 Gmail adapter implementation for Mail Intake.
 
 This module provides a **Gmail-specific implementation** of the
 `MailIntakeAdapter` contract.
 
 It is the only place in the codebase where:
-
-- `googleapiclient` is imported.
-- Gmail REST API semantics are known.
-- Low-level `.execute()` calls are made.
+- `googleapiclient` is imported
+- Gmail REST API semantics are known
+- Low-level `.execute()` calls are made
 
 All Gmail-specific behavior must be strictly contained within this module.
 """
 
-from collections.abc import Iterator
-from typing import Any
+from typing import Iterator, Dict, Any
 
 from googleapiclient.discovery import build
 from googleapiclient.errors import HttpError
 
 from mail_intake.adapters.base import MailIntakeAdapter
-from mail_intake.auth.base import MailIntakeAuthProvider
 from mail_intake.exceptions import MailIntakeAdapterError
+from mail_intake.auth.base import MailIntakeAuthProvider
 
 
 class MailIntakeGmailAdapter(MailIntakeAdapter):
@@ -34,18 +30,15 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
     Gmail REST API. It translates the generic mail intake contract into
     Gmail-specific API calls.
 
-    Notes:
-        **Responsibilities:**
+    This class is the ONLY place where:
+    - googleapiclient is imported
+    - Gmail REST semantics are known
+    - .execute() is called
 
-            - This class is the ONLY place where `googleapiclient` is imported.
-            - Gmail REST semantics are known.
-            - `.execute()` is called.
-
-        **Constraints:**
-
-            - Must remain thin and imperative.
-            - Must not perform parsing or interpretation.
-            - Must not expose Gmail-specific types beyond this class.
+    Design constraints:
+    - Must remain thin and imperative
+    - Must not perform parsing or interpretation
+    - Must not expose Gmail-specific types beyond this class
     """
 
     def __init__(
@@ -57,11 +50,9 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Initialize the Gmail adapter.
 
         Args:
-            auth_provider (MailIntakeAuthProvider):
-                Authentication provider capable of supplying valid Gmail API credentials.
-
-            user_id (str):
-                Gmail user identifier. Defaults to `"me"`.
+            auth_provider: Authentication provider capable of supplying
+                valid Gmail API credentials.
+            user_id: Gmail user identifier. Defaults to `"me"`.
         """
         self._auth_provider = auth_provider
         self._user_id = user_id
@@ -72,9 +63,11 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         """
         Lazily initialize and return the Gmail API service client.
 
+        Returns:
+            Initialized Gmail API service instance.
+
         Raises:
-            MailIntakeAdapterError:
-                If the Gmail service cannot be initialized.
+            MailIntakeAdapterError: If the Gmail service cannot be initialized.
         """
         if self._service is None:
             try:
@@ -86,25 +79,26 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                 ) from exc
         return self._service
 
-    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
+    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
         """
         Iterate over message references matching the query.
 
         Args:
-            query (str):
-                Gmail search query string.
+            query: Gmail search query string.
 
         Yields:
-            dict[str, str]:
-                Dictionaries containing ``message_id`` and ``thread_id``.
+            Dictionaries containing:
+            - ``message_id``: Gmail message ID
+            - ``thread_id``: Gmail thread ID
 
         Raises:
-            MailIntakeAdapterError:
-                If the Gmail API returns an error.
+            MailIntakeAdapterError: If the Gmail API returns an error.
         """
         try:
             request = (
-                self.service.users().messages().list(userId=self._user_id, q=query)
+                self.service.users()
+                .messages()
+                .list(userId=self._user_id, q=query)
             )
 
             while request is not None:
@@ -116,28 +110,29 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                         "thread_id": msg["threadId"],
                     }
 
-                request = self.service.users().messages().list_next(request, response)
+                request = (
+                    self.service.users()
+                    .messages()
+                    .list_next(request, response)
+                )
 
         except HttpError as exc:
             raise MailIntakeAdapterError(
                 "Gmail API error while listing messages"
             ) from exc
 
-    def fetch_message(self, message_id: str) -> dict[str, Any]:
+    def fetch_message(self, message_id: str) -> Dict[str, Any]:
         """
         Fetch a full Gmail message by message ID.
 
         Args:
-            message_id (str):
-                Gmail message identifier.
+            message_id: Gmail message identifier.
 
         Returns:
-            dict[str, Any]:
-                Provider-native Gmail message payload.
+            Provider-native Gmail message payload.
 
         Raises:
-            MailIntakeAdapterError:
-                If the Gmail API returns an error.
+            MailIntakeAdapterError: If the Gmail API returns an error.
         """
         try:
             return (
@@ -151,21 +146,18 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                 f"Gmail API error while fetching message {message_id}"
             ) from exc
 
-    def fetch_thread(self, thread_id: str) -> dict[str, Any]:
+    def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
         """
         Fetch a full Gmail thread by thread ID.
 
         Args:
-            thread_id (str):
-                Gmail thread identifier.
+            thread_id: Gmail thread identifier.
 
         Returns:
-            dict[str, Any]:
-                Provider-native Gmail thread payload.
+            Provider-native Gmail thread payload.
 
         Raises:
-            MailIntakeAdapterError:
-                If the Gmail API returns an error.
+            MailIntakeAdapterError: If the Gmail API returns an error.
         """
         try:
             return (

mail_intake/adapters/gmail.pyi

@@ -1,15 +1,11 @@
-from collections.abc import Iterator
-from typing import Any
-
+from typing import Iterator, Dict, Any
 from mail_intake.adapters.base import MailIntakeAdapter
 from mail_intake.auth.base import MailIntakeAuthProvider
 
 class MailIntakeGmailAdapter(MailIntakeAdapter):
-    def __init__(
-        self, auth_provider: MailIntakeAuthProvider[Any], user_id: str = ...
-    ) -> None: ...
+    def __init__(self, auth_provider: MailIntakeAuthProvider, user_id: str = ...) -> None: ...
     @property
     def service(self) -> Any: ...
-    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
-    def fetch_message(self, message_id: str) -> dict[str, Any]: ...
-    def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...
+    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
+    def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
+    def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...

mail_intake/auth/__init__.py

@@ -1,33 +1,20 @@
 """
-# Summary
-
 Authentication provider implementations for Mail Intake.
 
 This package defines the **authentication layer** used by mail adapters
 to obtain provider-specific credentials.
 
 It exposes:
-
-- A stable, provider-agnostic authentication contract.
-- Concrete authentication providers for supported platforms.
+- A stable, provider-agnostic authentication contract
+- Concrete authentication providers for supported platforms
 
 Authentication providers:
-
-- Are responsible for credential acquisition and lifecycle management.
-- Are intentionally decoupled from adapter logic.
-- May be extended by users to support additional providers.
+- Are responsible for credential acquisition and lifecycle management
+- Are intentionally decoupled from adapter logic
+- May be extended by users to support additional providers
 
 Consumers should depend on the abstract interface and use concrete
 implementations only where explicitly required.
-
----
-
-# Public API
-
-- `MailIntakeAuthProvider`
-- `MailIntakeGoogleAuth`
-
----
 """
 
 from .base import MailIntakeAuthProvider

mail_intake/auth/base.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Authentication provider contracts for Mail Intake.
 
 This module defines the **authentication abstraction layer** used by mail
@@ -25,20 +23,15 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
     providers and mail adapters by requiring providers to explicitly
     declare the type of credentials they return.
 
-    Notes:
-        **Responsibilities:**
+    Authentication providers encapsulate all logic required to:
+    - Acquire credentials from an external provider
+    - Refresh or revalidate credentials as needed
+    - Handle authentication-specific failure modes
+    - Coordinate with credential persistence layers where applicable
 
-            - Acquire credentials from an external provider.
-            - Refresh or revalidate credentials as needed.
-            - Handle authentication-specific failure modes.
-            - Coordinate with credential persistence layers where applicable.
-
-        **Constraints:**
-
-            - Mail adapters must treat returned credentials as opaque and
-              provider-specific.
-            - Mail adapters rely only on the declared credential type expected
-              by the adapter.
+    Mail adapters must treat returned credentials as opaque and
+    provider-specific, relying only on the declared credential type
+    expected by the adapter.
     """
 
     @abstractmethod
@@ -46,23 +39,21 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
         """
         Retrieve valid, provider-specific credentials.
 
+        This method is synchronous by design and represents the sole
+        entry point through which adapters obtain authentication
+        material.
+
+        Implementations must either return credentials of the declared
+        type ``T`` that are valid at the time of return or raise an
+        authentication-specific exception.
+
         Returns:
-            T:
-                Credentials of type `T` suitable for immediate use by the
-                corresponding mail adapter.
+            Credentials of type ``T`` suitable for immediate use by the
+            corresponding mail adapter.
 
         Raises:
             Exception:
                 An authentication-specific exception indicating that
                 credentials could not be obtained or validated.
-
-        Notes:
-            **Guarantees:**
-
-                - This method is synchronous by design.
-                - Represents the sole entry point through which adapters obtain
-                  authentication material.
-                - Implementations must either return credentials of the declared
-                  type `T` that are valid at the time of return or raise an exception.
         """
         raise NotImplementedError

mail_intake/auth/google.py

@@ -1,28 +1,25 @@
 """
-# Summary
-
 Google authentication provider implementation for Mail Intake.
 
 This module provides a **Google OAuth–based authentication provider**
 used primarily for Gmail access.
 
 It encapsulates all Google-specific authentication concerns, including:
-
-- Credential loading and persistence.
-- Token refresh handling.
-- Interactive OAuth flow initiation.
-- Coordination with a credential persistence layer.
+- Credential loading and persistence
+- Token refresh handling
+- Interactive OAuth flow initiation
+- Coordination with a credential persistence layer
 
 No Google authentication details should leak outside this module.
 """
 
 import os
-from collections.abc import Sequence
+from typing import Sequence
 
 import google.auth.exceptions
 from google.auth.transport.requests import Request
-from google.oauth2.credentials import Credentials
 from google_auth_oauthlib.flow import InstalledAppFlow
+from google.oauth2.credentials import Credentials
 
 from mail_intake.auth.base import MailIntakeAuthProvider
 from mail_intake.credentials.store import CredentialStore
@@ -36,18 +33,13 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
     This provider implements the `MailIntakeAuthProvider` interface using
     Google's OAuth 2.0 flow and credential management libraries.
 
-    Notes:
-        **Responsibilities:**
+    Responsibilities:
+    - Load cached credentials from a credential store when available
+    - Refresh expired credentials when possible
+    - Initiate an interactive OAuth flow only when required
+    - Persist refreshed or newly obtained credentials via the store
 
-            - Load cached credentials from a credential store when available.
-            - Refresh expired credentials when possible.
-            - Initiate an interactive OAuth flow only when required.
-            - Persist refreshed or newly obtained credentials via the store.
-
-        **Guarantees:**
-
-            - This class is synchronous by design and maintains a minimal
-              internal state.
+    This class is synchronous by design and maintains a minimal internal state.
     """
 
     def __init__(
@@ -60,13 +52,15 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         Initialize the Google authentication provider.
 
         Args:
-            credentials_path (str):
-                Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
+            credentials_path:
+                Path to the Google OAuth client secrets file used to
+                initiate the OAuth 2.0 flow.
 
-            store (CredentialStore[Credentials]):
-                Credential store responsible for persisting and retrieving Google OAuth credentials.
+            store:
+                Credential store responsible for persisting and
+                retrieving Google OAuth credentials.
 
-            scopes (Sequence[str]):
+            scopes:
                 OAuth scopes required for Gmail access.
         """
         self.credentials_path = credentials_path
@@ -77,23 +71,19 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         """
         Retrieve valid Google OAuth credentials.
 
+        This method attempts to:
+        1. Load cached credentials from the configured credential store
+        2. Refresh expired credentials when possible
+        3. Perform an interactive OAuth login as a fallback
+        4. Persist valid credentials for future use
+
         Returns:
-            Credentials:
-                A `google.oauth2.credentials.Credentials` instance suitable
-                for use with Google API clients.
+            A ``google.oauth2.credentials.Credentials`` instance suitable
+            for use with Google API clients.
 
         Raises:
-            MailIntakeAuthError:
-                If credentials cannot be loaded, refreshed,
+            MailIntakeAuthError: If credentials cannot be loaded, refreshed,
                 or obtained via interactive authentication.
-
-        Notes:
-            **Lifecycle:**
-
-                - Load cached credentials from the configured credential store.
-                - Refresh expired credentials when possible.
-                - Perform an interactive OAuth login as a fallback.
-                - Persist valid credentials for future use.
         """
         creds = self.store.load()
 

mail_intake/auth/google.pyi

@@ -1,11 +1,7 @@
-from collections.abc import Sequence
-from typing import Any
-
+from typing import Sequence, Any
 from mail_intake.auth.base import MailIntakeAuthProvider
 from mail_intake.credentials.store import CredentialStore
 
 class MailIntakeGoogleAuth(MailIntakeAuthProvider[Any]):
-    def __init__(
-        self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str]
-    ) -> None: ...
+    def __init__(self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str]) -> None: ...
     def get_credentials(self) -> Any: ...

mail_intake/config.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Global configuration models for Mail Intake.
 
 This module defines the **top-level configuration object** used to control
@@ -12,45 +10,36 @@ environment reads to ensure predictability and testability.
 """
 
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass(frozen=True)
 class MailIntakeConfig:
     """
-    Global configuration for `mail-intake`.
+    Global configuration for mail-intake.
 
-    Notes:
-        **Guarantees:**
+    This configuration is intentionally explicit and immutable.
+    No implicit environment reads or global state.
 
-            - This configuration is intentionally explicit and immutable.
-            - No implicit environment reads or global state.
-            - Explicit configuration over implicit defaults.
-            - No direct environment or filesystem access.
-            - This model is safe to pass across layers and suitable for
-              serialization.
+    Design principles:
+    - Immutable once constructed
+    - Explicit configuration over implicit defaults
+    - No direct environment or filesystem access
+
+    This model is safe to pass across layers and suitable for serialization.
     """
 
     provider: str = "gmail"
-    """
-    Identifier of the mail provider to use (e.g., ``"gmail"``).
-    """
+    """Identifier of the mail provider to use (e.g., ``"gmail"``)."""
 
     user_id: str = "me"
-    """
-    Provider-specific user identifier. Defaults to the authenticated user.
-    """
+    """Provider-specific user identifier. Defaults to the authenticated user."""
 
     readonly: bool = True
-    """
-    Whether ingestion should operate in read-only mode.
-    """
+    """Whether ingestion should operate in read-only mode."""
 
-    credentials_path: str | None = None
-    """
-    Optional path to provider credentials configuration.
-    """
+    credentials_path: Optional[str] = None
+    """Optional path to provider credentials configuration."""
 
-    token_path: str | None = None
-    """
-    Optional path to persisted authentication tokens.
-    """
+    token_path: Optional[str] = None
+    """Optional path to persisted authentication tokens."""

mail_intake/config.pyi

@@ -1,14 +1,9 @@
+from typing import Optional
+
 class MailIntakeConfig:
     provider: str
     user_id: str
     readonly: bool
-    credentials_path: str | None
-    token_path: str | None
-    def __init__(
-        self,
-        provider: str = ...,
-        user_id: str = ...,
-        readonly: bool = ...,
-        credentials_path: str | None = ...,
-        token_path: str | None = ...,
-    ) -> None: ...
+    credentials_path: Optional[str]
+    token_path: Optional[str]
+    def __init__(self, provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[str] = ...) -> None: ...

mail_intake/credentials/__init__.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Credential persistence interfaces and implementations for Mail Intake.
 
 This package defines the abstractions and concrete implementations used
@@ -12,23 +10,12 @@ credential acquisition, validation, and refresh, while implementations
 within this package are responsible solely for storage and retrieval.
 
 The package provides:
-
-- A generic `CredentialStore` abstraction defining the persistence contract.
-- Local filesystem–based storage for development and single-node use.
-- Distributed, Redis-backed storage for production and scaled deployments.
+- A generic ``CredentialStore`` abstraction defining the persistence contract
+- Local filesystem–based storage for development and single-node use
+- Distributed, Redis-backed storage for production and scaled deployments
 
 Credential lifecycle management, interpretation, and security policy
 decisions remain the responsibility of authentication providers.
-
----
-
-# Public API
-
-- `CredentialStore`
-- `PickleCredentialStore`
-- `RedisCredentialStore`
-
----
 """
 
 from mail_intake.credentials.store import CredentialStore

mail_intake/credentials/__init__.pyi

@@ -1,5 +1,5 @@
+from .store import CredentialStore
 from .pickle import PickleCredentialStore
 from .redis import RedisCredentialStore
-from .store import CredentialStore
 
 __all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"]

mail_intake/credentials/pickle.py

@@ -1,22 +1,20 @@
 """
-# Summary
-
 Local filesystem–based credential persistence for Mail Intake.
 
 This module provides a file-backed implementation of the
-`CredentialStore` abstraction using Python's `pickle` module.
+``CredentialStore`` abstraction using Python's ``pickle`` module.
 
-The `pickle`-based credential store is intended for local development,
+The pickle-based credential store is intended for local development,
 single-node deployments, and controlled environments where credentials
 do not need to be shared across processes or machines.
 
-Due to the security and portability risks associated with `pickle`-based
+Due to the security and portability risks associated with pickle-based
 serialization, this implementation is not suitable for distributed or
 untrusted environments.
 """
 
 import pickle
-from typing import TypeVar
+from typing import Optional, TypeVar
 
 from mail_intake.credentials.store import CredentialStore
 
@@ -31,17 +29,13 @@ class PickleCredentialStore(CredentialStore[T]):
     filesystem. It is a simple implementation intended primarily for
     development, testing, and single-process execution contexts.
 
-    Notes:
-        **Guarantees:**
+    This implementation:
+    - Stores credentials on the local filesystem
+    - Uses pickle for serialization and deserialization
+    - Does not provide encryption, locking, or concurrency guarantees
 
-            - Stores credentials on the local filesystem.
-            - Uses `pickle` for serialization and deserialization.
-            - Does not provide encryption, locking, or concurrency guarantees.
-
-        **Constraints:**
-
-            - Credential lifecycle management, validation, and refresh logic are
-              explicitly out of scope for this class.
+    Credential lifecycle management, validation, and refresh logic are
+    explicitly out of scope for this class.
     """
 
     def __init__(self, path: str):
@@ -49,28 +43,25 @@ class PickleCredentialStore(CredentialStore[T]):
         Initialize a pickle-backed credential store.
 
         Args:
-            path (str):
+            path:
                 Filesystem path where credentials will be stored.
                 The file will be created or overwritten as needed.
         """
         self.path = path
 
-    def load(self) -> T | None:
+    def load(self) -> Optional[T]:
         """
         Load credentials from the local filesystem.
 
+        If the credential file does not exist or cannot be successfully
+        deserialized, this method returns ``None``.
+
+        The store does not attempt to validate or interpret the returned
+        credentials.
+
         Returns:
-            T | None:
-                An instance of type `T` if credentials are present and
-                successfully deserialized; otherwise `None`.
-
-        Notes:
-            **Guarantees:**
-
-                - If the credential file does not exist or cannot be successfully
-                  deserialized, this method returns `None`.
-                - The store does not attempt to validate or interpret the
-                  returned credentials.
+            An instance of type ``T`` if credentials are present and
+            successfully deserialized; otherwise ``None``.
         """
         try:
             with open(self.path, "rb") as fh:
@@ -82,14 +73,12 @@ class PickleCredentialStore(CredentialStore[T]):
         """
         Persist credentials to the local filesystem.
 
+        Any previously stored credentials at the configured path are
+        overwritten.
+
         Args:
-            credentials (T):
+            credentials:
                 The credential object to persist.
-
-        Notes:
-            **Responsibilities:**
-
-                - Any previously stored credentials at the configured path are overwritten
         """
         with open(self.path, "wb") as fh:
             pickle.dump(credentials, fh)
@@ -98,10 +87,8 @@ class PickleCredentialStore(CredentialStore[T]):
         """
         Remove persisted credentials from the local filesystem.
 
-        Notes:
-            **Lifecycle:**
-
-                - This method deletes the credential file if it exists and should be treated as an idempotent operation
+        This method deletes the credential file if it exists and should
+        be treated as an idempotent operation.
         """
         import os
 

mail_intake/credentials/pickle.pyi

@@ -1,5 +1,4 @@
-from typing import TypeVar
-
+from typing import Optional, TypeVar
 from .store import CredentialStore
 
 T = TypeVar("T")
@@ -7,6 +6,6 @@ T = TypeVar("T")
 class PickleCredentialStore(CredentialStore[T]):
     path: str
     def __init__(self, path: str) -> None: ...
-    def load(self) -> T | None: ...
+    def load(self) -> Optional[T]: ...
     def save(self, credentials: T) -> None: ...
     def clear(self) -> None: ...

mail_intake/credentials/redis.py

@@ -1,10 +1,8 @@
 """
-# Summary
-
 Redis-backed credential persistence for Mail Intake.
 
 This module provides a Redis-based implementation of the
-`CredentialStore` abstraction, enabling credential persistence
+``CredentialStore`` abstraction, enabling credential persistence
 across distributed and horizontally scaled deployments.
 
 The Redis credential store is designed for environments where
@@ -13,19 +11,18 @@ processes, containers, or nodes, such as container orchestration
 platforms and microservice architectures.
 
 Key characteristics:
-
-- Distributed-safe, shared storage using Redis.
-- Explicit, caller-defined serialization and deserialization.
-- No reliance on unsafe mechanisms such as `pickle`.
-- Optional time-to-live (TTL) support for automatic credential expiry.
+- Distributed-safe, shared storage using Redis
+- Explicit, caller-defined serialization and deserialization
+- No reliance on unsafe mechanisms such as pickle
+- Optional time-to-live (TTL) support for automatic credential expiry
 
 This module is responsible solely for persistence concerns.
 Credential validation, refresh, rotation, and acquisition remain the
 responsibility of authentication provider implementations.
 """
 
-from collections.abc import Callable
-from typing import Any, TypeVar
+
+from typing import Optional, TypeVar, Callable
 
 from mail_intake.credentials.store import CredentialStore
 
@@ -34,50 +31,59 @@ T = TypeVar("T")
 
 class RedisCredentialStore(CredentialStore[T]):
     """
-    Redis-backed implementation of `CredentialStore`.
+    Redis-backed implementation of ``CredentialStore``.
 
     This store persists credentials in Redis and is suitable for
     distributed and horizontally scaled deployments where credentials
     must be shared across multiple processes or nodes.
 
-    Notes:
-        **Responsibilities:**
+    The store is intentionally generic and delegates all serialization
+    concerns to caller-provided functions. This avoids unsafe mechanisms
+    such as pickle and allows credential formats to be explicitly
+    controlled and audited.
 
-            - This class is responsible only for persistence and retrieval.
-            - It does not interpret, validate, refresh, or otherwise manage the
-              lifecycle of the credentials being stored.
-
-        **Guarantees:**
-
-            - The store is intentionally generic and delegates all serialization
-              concerns to caller-provided functions.
-            - This avoids unsafe mechanisms such as `pickle` and allows
-              credential formats to be explicitly controlled and audited.
+    This class is responsible only for persistence and retrieval.
+    It does not interpret, validate, refresh, or otherwise manage
+    the lifecycle of the credentials being stored.
     """
 
     def __init__(
         self,
-        redis_client: Any,
+        redis_client,
         key: str,
         serialize: Callable[[T], bytes],
         deserialize: Callable[[bytes], T],
-        ttl_seconds: int | None = None,
+        ttl_seconds: Optional[int] = None,
     ):
         """
         Initialize a Redis-backed credential store.
 
         Args:
-            redis_client (Any):
-                Initialized Redis client instance used for persistence.
-            key (str):
-                Storage key under which credentials are persisted.
-            serialize (Callable[[T], bytes]):
-                Callable that encodes credentials to bytes for storage.
-            deserialize (Callable[[bytes], T]):
-                Callable that decodes stored bytes back into credentials.
-            ttl_seconds (int | None):
-                Optional time-to-live in seconds after which stored
-                credentials expire automatically. ``None`` disables expiry.
+            redis_client:
+                An initialized Redis client instance (for example,
+                ``redis.Redis`` or a compatible interface) used to
+                communicate with the Redis server.
+
+            key:
+                The Redis key under which credentials are stored.
+                Callers are responsible for applying appropriate
+                namespacing to avoid collisions.
+
+            serialize:
+                A callable that converts a credential object of type
+                ``T`` into a ``bytes`` representation suitable for
+                storage in Redis.
+
+            deserialize:
+                A callable that converts a ``bytes`` payload retrieved
+                from Redis back into a credential object of type ``T``.
+
+            ttl_seconds:
+                Optional time-to-live (TTL) for the stored credentials,
+                expressed in seconds. When provided, Redis will
+                automatically expire the stored credentials after the
+                specified duration. If ``None``, credentials are stored
+                without an expiration.
         """
         self.redis = redis_client
         self.key = key
@@ -85,24 +91,20 @@ class RedisCredentialStore(CredentialStore[T]):
         self.deserialize = deserialize
         self.ttl_seconds = ttl_seconds
 
-    def load(self) -> T | None:
+    def load(self) -> Optional[T]:
         """
         Load credentials from Redis.
 
+        If no value exists for the configured key, or if the stored
+        payload cannot be successfully deserialized, this method
+        returns ``None``.
+
+        The store does not attempt to validate the returned credentials
+        or determine whether they are expired or otherwise usable.
+
         Returns:
-            T | None:
-                An instance of type `T` if credentials are present and
-                successfully deserialized; otherwise `None`.
-
-        Notes:
-            **Guarantees:**
-
-                - If no value exists for the configured key, or if the stored
-                  payload cannot be successfully deserialized, this method
-                  returns `None`.
-                - The store does not attempt to validate the returned
-                  credentials or determine whether they are expired or
-                  otherwise usable.
+            An instance of type ``T`` if credentials are present and
+            successfully deserialized; otherwise ``None``.
         """
         raw = self.redis.get(self.key)
         if not raw:
@@ -116,15 +118,13 @@ class RedisCredentialStore(CredentialStore[T]):
         """
         Persist credentials to Redis.
 
+        Any previously stored credentials under the same key are
+        overwritten. If a TTL is configured, the credentials will
+        expire automatically after the specified duration.
+
         Args:
-            credentials (T):
+            credentials:
                 The credential object to persist.
-
-        Notes:
-            **Responsibilities:**
-
-                - Any previously stored credentials under the same key are overwritten
-                - If a TTL is configured, the credentials will expire automatically after the specified duration
         """
         payload = self.serialize(credentials)
         if self.ttl_seconds:
@@ -136,10 +136,7 @@ class RedisCredentialStore(CredentialStore[T]):
         """
         Remove stored credentials from Redis.
 
-        Notes:
-            **Lifecycle:**
-
-                - This operation deletes the configured Redis key if it exists
-                - Implementations should treat this method as idempotent
+        This operation deletes the configured Redis key if it exists.
+        Implementations should treat this method as idempotent.
         """
         self.redis.delete(self.key)

mail_intake/credentials/redis.pyi

@@ -1,6 +1,4 @@
-from collections.abc import Callable
-from typing import Any, TypeVar
-
+from typing import Optional, TypeVar, Callable, Any
 from .store import CredentialStore
 
 T = TypeVar("T")
@@ -10,15 +8,8 @@ class RedisCredentialStore(CredentialStore[T]):
     key: str
     serialize: Callable[[T], bytes]
     deserialize: Callable[[bytes], T]
-    ttl_seconds: int | None
-    def __init__(
-        self,
-        redis_client: Any,
-        key: str,
-        serialize: Callable[[T], bytes],
-        deserialize: Callable[[bytes], T],
-        ttl_seconds: int | None = ...,
-    ) -> None: ...
-    def load(self) -> T | None: ...
+    ttl_seconds: Optional[int]
+    def __init__(self, redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = ...) -> None: ...
+    def load(self) -> Optional[T]: ...
     def save(self, credentials: T) -> None: ...
     def clear(self) -> None: ...

mail_intake/credentials/store.py

@@ -1,12 +1,10 @@
 """
-# Summary
-
 Credential persistence abstractions for Mail Intake.
 
 This module defines the generic persistence contract used to store and
 retrieve authentication credentials across Mail Intake components.
 
-The `CredentialStore` abstraction establishes a strict separation
+The ``CredentialStore`` abstraction establishes a strict separation
 between credential *lifecycle management* and credential *storage*.
 Authentication providers are responsible for acquiring, validating,
 refreshing, and revoking credentials, while concrete store
@@ -19,51 +17,45 @@ or secrets managers—without coupling authentication logic to any
 specific storage mechanism.
 """
 
+
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar
+from typing import Generic, Optional, TypeVar
 
 T = TypeVar("T")
 
 
 class CredentialStore(ABC, Generic[T]):
     """
-    Abstract base class defining a generic persistence interface.
+    Abstract base class defining a generic persistence interface for
+    authentication credentials.
 
-    Used for authentication credentials across different backends.
+    This interface separates *credential lifecycle management* from
+    *credential storage mechanics*. Implementations are responsible
+    only for persistence concerns, while authentication providers
+    retain full control over credential creation, validation, refresh,
+    and revocation logic.
 
-    Notes:
-        **Responsibilities:**
-
-            - Provide persistent storage separating life-cycle management from
-              storage mechanics.
-            - Keep implementation focused only on persistence.
-
-        **Constraints:**
-
-            - The store is intentionally agnostic to:
-                - The concrete credential type being stored.
-                - The serialization format used to persist credentials.
-                - The underlying storage backend or durability guarantees.
+    The store is intentionally agnostic to:
+    - The concrete credential type being stored
+    - The serialization format used to persist credentials
+    - The underlying storage backend or durability guarantees
     """
 
     @abstractmethod
-    def load(self) -> T | None:
+    def load(self) -> Optional[T]:
         """
         Load previously persisted credentials.
 
+        Implementations should return ``None`` when no credentials are
+        present or when stored credentials cannot be successfully
+        decoded or deserialized.
+
+        The store must not attempt to validate, refresh, or otherwise
+        interpret the returned credentials.
+
         Returns:
-            T | None:
-                An instance of type `T` if credentials are available and
-                loadable; otherwise `None`.
-
-        Notes:
-            **Guarantees:**
-
-                - Implementations should return `None` when no credentials are
-                  present or when stored credentials cannot be successfully
-                  decoded or deserialized.
-                - The store must not attempt to validate, refresh, or otherwise
-                  interpret the returned credentials.
+            An instance of type ``T`` if credentials are available and
+            loadable; otherwise ``None``.
         """
 
     @abstractmethod
@@ -71,20 +63,18 @@ class CredentialStore(ABC, Generic[T]):
         """
         Persist credentials to the underlying storage backend.
 
+        This method is invoked when credentials are newly obtained or
+        have been refreshed and are known to be valid at the time of
+        persistence.
+
+        Implementations are responsible for:
+        - Ensuring durability appropriate to the deployment context
+        - Applying encryption or access controls where required
+        - Overwriting any previously stored credentials
+
         Args:
-            credentials (T):
+            credentials:
                 The credential object to persist.
-
-        Notes:
-            **Lifecycle:**
-
-                - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence
-
-            **Responsibilities:**
-
-                - Ensuring durability appropriate to the deployment context
-                - Applying encryption or access controls where required
-                - Overwriting any previously stored credentials
         """
 
     @abstractmethod
@@ -92,13 +82,9 @@ class CredentialStore(ABC, Generic[T]):
         """
         Remove any persisted credentials from the store.
 
-        Notes:
-            **Lifecycle:**
+        This method is called when credentials are known to be invalid,
+        revoked, corrupted, or otherwise unusable, and must ensure that
+        no stale authentication material remains accessible.
 
-                - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable
-                - Must ensure that no stale authentication material remains accessible
-
-            **Guarantees:**
-
-                - Implementations should treat this operation as idempotent
+        Implementations should treat this operation as idempotent.
         """

mail_intake/credentials/store.pyi

@@ -1,11 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar
+from typing import Generic, Optional, TypeVar
 
 T = TypeVar("T")
 
 class CredentialStore(ABC, Generic[T]):
     @abstractmethod
-    def load(self) -> T | None: ...
+    def load(self) -> Optional[T]: ...
     @abstractmethod
     def save(self, credentials: T) -> None: ...
     @abstractmethod

mail_intake/exceptions.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Exception hierarchy for Mail Intake.
 
 This module defines the **canonical exception types** used throughout the
@@ -16,12 +14,11 @@ class MailIntakeError(Exception):
     """
     Base exception for all Mail Intake errors.
 
-    Notes:
-        **Guarantees:**
+    This is the root of the Mail Intake exception hierarchy.
+    All errors raised by the library must derive from this class.
 
-            - This is the root of the Mail Intake exception hierarchy
-            - All errors raised by the library must derive from this class
-            - Consumers should generally catch this type when handling library-level failures
+    Consumers should generally catch this type when handling
+    library-level failures.
     """
 
 
@@ -29,11 +26,8 @@ class MailIntakeAuthError(MailIntakeError):
     """
     Authentication and credential-related failures.
 
-    Notes:
-        **Lifecycle:**
-
-            - Raised when authentication providers are unable to acquire,
-              refresh, or persist valid credentials.
+    Raised when authentication providers are unable to acquire,
+    refresh, or persist valid credentials.
     """
 
 
@@ -41,11 +35,8 @@ class MailIntakeAdapterError(MailIntakeError):
     """
     Errors raised by mail provider adapters.
 
-    Notes:
-        **Lifecycle:**
-
-            - Raised when a provider adapter encounters API errors, transport
-              failures, or invalid provider responses.
+    Raised when a provider adapter encounters API errors,
+    transport failures, or invalid provider responses.
     """
 
 
@@ -53,9 +44,6 @@ class MailIntakeParsingError(MailIntakeError):
     """
     Errors encountered while parsing message content.
 
-    Notes:
-        **Lifecycle:**
-
-            - Raised when raw provider payloads cannot be interpreted or
-              normalized into internal domain models.
+    Raised when raw provider payloads cannot be interpreted
+    or normalized into internal domain models.
     """

mail_intake/ingestion/__init__.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Mail ingestion orchestration for Mail Intake.
 
 This package contains **high-level ingestion components** responsible for
@@ -10,22 +8,13 @@ It represents the **top of the ingestion pipeline** and is intended to be the
 primary interaction surface for library consumers.
 
 Components in this package:
-
-- Are provider-agnostic.
-- Depend only on adapter and parser contracts.
-- Contain no provider-specific API logic.
-- Expose read-only ingestion workflows.
+- Are provider-agnostic
+- Depend only on adapter and parser contracts
+- Contain no provider-specific API logic
+- Expose read-only ingestion workflows
 
 Consumers are expected to construct a mail adapter and pass it to the
 ingestion layer to begin processing messages and threads.
-
----
-
-# Public API
-
-- `MailIntakeReader`
-
----
 """
 
 from .reader import MailIntakeReader

mail_intake/ingestion/reader.py

@@ -1,53 +1,47 @@
 """
-# Summary
-
 High-level mail ingestion orchestration for Mail Intake.
 
 This module provides the primary, provider-agnostic entry point for
 reading and processing mail data.
 
 It coordinates:
-
-- Mail adapter access.
-- Message and thread iteration.
-- Header and body parsing.
-- Normalization and model construction.
+- Mail adapter access
+- Message and thread iteration
+- Header and body parsing
+- Normalization and model construction
 
 No provider-specific logic or API semantics are permitted in this layer.
 """
 
-from collections.abc import Iterator
 from datetime import datetime
-from typing import Any
+from typing import Iterator, Dict, Any
 
 from mail_intake.adapters.base import MailIntakeAdapter
-from mail_intake.exceptions import MailIntakeParsingError
 from mail_intake.models.message import MailIntakeMessage
 from mail_intake.models.thread import MailIntakeThread
+from mail_intake.parsers.headers import parse_headers, extract_sender
 from mail_intake.parsers.body import extract_body
-from mail_intake.parsers.headers import extract_sender, parse_headers
 from mail_intake.parsers.subject import normalize_subject
+from mail_intake.exceptions import MailIntakeParsingError
 
 
 class MailIntakeReader:
     """
     High-level read-only ingestion interface.
 
-    Notes:
-        **Responsibilities:**
+    This class is the **primary entry point** for consumers of the Mail
+    Intake library.
 
-            - This class is the primary entry point for consumers of the
-              Mail Intake library.
-            - It orchestrates the full ingestion pipeline:
-                - Querying the adapter for message references.
-                - Fetching raw provider messages.
-                - Parsing and normalizing message data.
-                - Constructing domain models.
+    It orchestrates the full ingestion pipeline:
+    - Querying the adapter for message references
+    - Fetching raw provider messages
+    - Parsing and normalizing message data
+    - Constructing domain models
 
-        **Constraints:**
-
-            - This class is intentionally: Provider-agnostic, stateless beyond
-              iteration scope, read-only.
+    This class is intentionally:
+    - Provider-agnostic
+    - Stateless beyond iteration scope
+    - Read-only
     """
 
     def __init__(self, adapter: MailIntakeAdapter):
@@ -55,8 +49,8 @@ class MailIntakeReader:
         Initialize the mail reader.
 
         Args:
-            adapter (MailIntakeAdapter):
-                Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
+            adapter: Mail adapter implementation used to retrieve raw
+                messages and threads from a mail provider.
         """
         self._adapter = adapter
 
@@ -65,16 +59,13 @@ class MailIntakeReader:
         Iterate over parsed messages matching a provider query.
 
         Args:
-            query (str):
-                Provider-specific query string used to filter messages.
+            query: Provider-specific query string used to filter messages.
 
         Yields:
-            MailIntakeMessage:
-                Fully parsed and normalized `MailIntakeMessage` instances.
+            Fully parsed and normalized `MailIntakeMessage` instances.
 
         Raises:
-            MailIntakeParsingError:
-                If a message cannot be parsed.
+            MailIntakeParsingError: If a message cannot be parsed.
         """
         for ref in self._adapter.iter_message_refs(query):
             raw = self._adapter.fetch_message(ref["message_id"])
@@ -84,25 +75,19 @@ class MailIntakeReader:
         """
         Iterate over threads constructed from messages matching a query.
 
+        Messages are grouped by `thread_id` and yielded as complete thread
+        objects containing all associated messages.
+
         Args:
-            query (str):
-                Provider-specific query string used to filter messages.
+            query: Provider-specific query string used to filter messages.
 
         Returns:
-            Iterator[MailIntakeThread]:
-                An iterator over `MailIntakeThread` instances.
+            An iterator of `MailIntakeThread` instances.
 
         Raises:
-            `MailIntakeParsingError`:
-                If a message cannot be parsed.
-
-        Notes:
-            **Guarantees:**
-
-                - Messages are grouped by `thread_id` and yielded as complete
-                  thread objects containing all associated messages.
+            MailIntakeParsingError: If a message cannot be parsed.
         """
-        threads: dict[str, MailIntakeThread] = {}
+        threads: Dict[str, MailIntakeThread] = {}
 
         for ref in self._adapter.iter_message_refs(query):
             raw = self._adapter.fetch_message(ref["message_id"])
@@ -120,21 +105,19 @@ class MailIntakeReader:
 
         return iter(threads.values())
 
-    def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage:
+    def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage:
         """
         Parse a raw provider message into a `MailIntakeMessage`.
 
         Args:
-            raw_message (dict[str, Any]):
-                Provider-native message payload.
+            raw_message: Provider-native message payload.
 
         Returns:
-            MailIntakeMessage:
-                A fully populated `MailIntakeMessage` instance.
+            A fully populated `MailIntakeMessage` instance.
 
         Raises:
-            MailIntakeParsingError:
-                If the message payload is missing required fields or cannot be parsed.
+            MailIntakeParsingError: If the message payload is missing required
+                fields or cannot be parsed.
         """
         try:
             message_id = raw_message["id"]

mail_intake/ingestion/reader.pyi

@@ -1,6 +1,4 @@
-from collections.abc import Iterator
-from typing import Any
-
+from typing import Iterator, Dict, Any
 from mail_intake.adapters.base import MailIntakeAdapter
 from mail_intake.models.message import MailIntakeMessage
 from mail_intake.models.thread import MailIntakeThread
@@ -9,4 +7,4 @@ class MailIntakeReader:
     def __init__(self, adapter: MailIntakeAdapter) -> None: ...
     def iter_messages(self, query: str) -> Iterator[MailIntakeMessage]: ...
     def iter_threads(self, query: str) -> Iterator[MailIntakeThread]: ...
-    def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage: ...
+    def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage: ...

mail_intake/models/__init__.py

@@ -1,28 +1,16 @@
 """
-# Summary
-
 Domain models for Mail Intake.
 
 This package defines the **canonical, provider-agnostic data models**
 used throughout the Mail Intake ingestion pipeline.
 
 Models in this package:
-
-- Represent fully parsed and normalized mail data.
-- Are safe to persist, serialize, and index.
-- Contain no provider-specific payloads or API semantics.
-- Serve as stable inputs for downstream processing and analysis.
+- Represent fully parsed and normalized mail data
+- Are safe to persist, serialize, and index
+- Contain no provider-specific payloads or API semantics
+- Serve as stable inputs for downstream processing and analysis
 
 These models form the core internal data contract of the library.
-
----
-
-# Public API
-
-- `MailIntakeMessage`
-- `MailIntakeThread`
-
----
 """
 
 from .message import MailIntakeMessage

mail_intake/models/message.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Message domain models for Mail Intake.
 
 This module defines the **canonical, provider-agnostic representation**
@@ -13,6 +11,7 @@ provider-specific fields or semantics.
 
 from dataclasses import dataclass
 from datetime import datetime
+from typing import Optional, Dict
 
 
 @dataclass(frozen=True)
@@ -20,60 +19,37 @@ class MailIntakeMessage:
     """
     Canonical internal representation of a single email message.
 
-    Notes:
-        **Guarantees:**
+    This model represents a fully parsed and normalized email message.
+    It is intentionally provider-agnostic and suitable for persistence,
+    indexing, and downstream processing.
 
-            - This model represents a fully parsed and normalized email message.
-            - It is intentionally provider-agnostic and suitable for
-              persistence, indexing, and downstream processing.
-
-        **Constraints:**
-
-            - No provider-specific identifiers, payloads, or API semantics
-              should appear in this model.
+    No provider-specific identifiers, payloads, or API semantics
+    should appear in this model.
     """
 
     message_id: str
-    """
-    Provider-specific message identifier.
-    """
+    """Provider-specific message identifier."""
 
     thread_id: str
-    """
-    Provider-specific thread identifier to which this message belongs.
-    """
+    """Provider-specific thread identifier to which this message belongs."""
 
     timestamp: datetime
-    """
-    Message timestamp as a timezone-naive UTC datetime.
-    """
+    """Message timestamp as a timezone-naive UTC datetime."""
 
     from_email: str
-    """
-    Sender email address.
-    """
+    """Sender email address."""
 
-    from_name: str | None
-    """
-    Optional human-readable sender name.
-    """
+    from_name: Optional[str]
+    """Optional human-readable sender name."""
 
     subject: str
-    """
-    Raw subject line of the message.
-    """
+    """Raw subject line of the message."""
 
     body_text: str
-    """
-    Extracted plain-text body content of the message.
-    """
+    """Extracted plain-text body content of the message."""
 
     snippet: str
-    """
-    Short provider-supplied preview snippet of the message.
-    """
+    """Short provider-supplied preview snippet of the message."""
 
-    raw_headers: dict[str, str]
-    """
-    Normalized mapping of message headers (header name → value).
-    """
+    raw_headers: Dict[str, str]
+    """Normalized mapping of message headers (header name → value)."""

mail_intake/models/message.pyi

@@ -1,24 +1,14 @@
 from datetime import datetime
+from typing import Optional, Dict
 
 class MailIntakeMessage:
     message_id: str
     thread_id: str
     timestamp: datetime
     from_email: str
-    from_name: str | None
+    from_name: Optional[str]
     subject: str
     body_text: str
     snippet: str
-    raw_headers: dict[str, str]
-    def __init__(
-        self,
-        message_id: str,
-        thread_id: str,
-        timestamp: datetime,
-        from_email: str,
-        from_name: str | None,
-        subject: str,
-        body_text: str,
-        snippet: str,
-        raw_headers: dict[str, str],
-    ) -> None: ...
+    raw_headers: Dict[str, str]
+    def __init__(self, message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str]) -> None: ...

mail_intake/models/thread.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Thread domain models for Mail Intake.
 
 This module defines the **canonical, provider-agnostic representation**
@@ -12,6 +10,7 @@ for higher-level correspondence workflows.
 
 from dataclasses import dataclass, field
 from datetime import datetime
+from typing import List, Set
 
 from mail_intake.models.message import MailIntakeMessage
 
@@ -21,55 +20,40 @@ class MailIntakeThread:
     """
     Canonical internal representation of an email thread.
 
-    Notes:
-        **Guarantees:**
+    A thread groups multiple related messages under a single subject
+    and participant set. It is designed to support reasoning over
+    conversational context such as job applications, interviews,
+    follow-ups, and ongoing discussions.
 
-            - A thread groups multiple related messages under a single subject
-              and participant set.
-            - It is designed to support reasoning over conversational context
-              such as job applications, interviews, follow-ups, and ongoing discussions.
-            - This model is provider-agnostic and safe to persist.
+    This model is provider-agnostic and safe to persist.
     """
 
     thread_id: str
-    """
-    Provider-specific thread identifier.
-    """
+    """Provider-specific thread identifier."""
 
     normalized_subject: str
-    """
-    Normalized subject line used to group related messages.
-    """
+    """Normalized subject line used to group related messages."""
 
-    participants: set[str] = field(default_factory=set)
-    """
-    Set of unique participant email addresses observed in the thread.
-    """
+    participants: Set[str] = field(default_factory=set)
+    """Set of unique participant email addresses observed in the thread."""
 
-    messages: list[MailIntakeMessage] = field(default_factory=list)
-    """
-    Ordered list of messages belonging to this thread.
-    """
+    messages: List[MailIntakeMessage] = field(default_factory=list)
+    """Ordered list of messages belonging to this thread."""
 
     last_activity_at: datetime | None = None
-    """
-    Timestamp of the most recent message in the thread.
-    """
+    """Timestamp of the most recent message in the thread."""
 
     def add_message(self, message: MailIntakeMessage) -> None:
         """
         Add a message to the thread and update derived fields.
 
+        This method:
+        - Appends the message to the thread
+        - Tracks unique participants
+        - Updates the last activity timestamp
+
         Args:
-            message (MailIntakeMessage):
-                Parsed mail message to add to the thread.
-
-        Notes:
-            **Responsibilities:**
-
-                - Appends the message to the thread.
-                - Tracks unique participants.
-                - Updates the last activity timestamp.
+            message: Parsed mail message to add to the thread.
         """
         self.messages.append(message)
 

mail_intake/models/thread.pyi

@@ -1,19 +1,12 @@
 from datetime import datetime
-
+from typing import List, Set, Optional
 from .message import MailIntakeMessage
 
 class MailIntakeThread:
     thread_id: str
     normalized_subject: str
-    participants: set[str]
-    messages: list[MailIntakeMessage]
-    last_activity_at: datetime | None
-    def __init__(
-        self,
-        thread_id: str,
-        normalized_subject: str,
-        participants: set[str] = ...,
-        messages: list[MailIntakeMessage] = ...,
-        last_activity_at: datetime | None = ...,
-    ) -> None: ...
+    participants: Set[str]
+    messages: List[MailIntakeMessage]
+    last_activity_at: Optional[datetime]
+    def __init__(self, thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...) -> None: ...
     def add_message(self, message: MailIntakeMessage) -> None: ...

mail_intake/parsers/__init__.py

@@ -1,36 +1,21 @@
 """
-# Summary
-
 Message parsing utilities for Mail Intake.
 
 This package contains **provider-aware but adapter-agnostic parsing helpers**
 used to extract and normalize structured information from raw mail payloads.
 
 Parsers in this package are responsible for:
-
-- Interpreting provider-native message structures.
-- Extracting meaningful fields such as headers, body text, and subjects.
-- Normalizing data into consistent internal representations.
+- Interpreting provider-native message structures
+- Extracting meaningful fields such as headers, body text, and subjects
+- Normalizing data into consistent internal representations
 
 This package does not:
-
-- Perform network or IO operations.
-- Contain provider API logic.
-- Construct domain models directly.
+- Perform network or IO operations
+- Contain provider API logic
+- Construct domain models directly
 
 Parsing functions are designed to be composable and are orchestrated by the
 ingestion layer.
-
----
-
-# Public API
-
-- `extract_body`
-- `parse_headers`
-- `extract_sender`
-- `normalize_subject`
-
----
 """
 
 from .body import extract_body

mail_intake/parsers/__init__.pyi

@@ -1,5 +1,5 @@
 from .body import extract_body
-from .headers import extract_sender, parse_headers
+from .headers import parse_headers, extract_sender
 from .subject import normalize_subject
 
 __all__ = ["extract_body", "parse_headers", "extract_sender", "normalize_subject"]

mail_intake/parsers/body.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Message body extraction utilities for Mail Intake.
 
 This module contains helper functions for extracting a best-effort
@@ -11,7 +9,7 @@ prefers human-readable text over fidelity to original formatting.
 """
 
 import base64
-from typing import Any
+from typing import Dict, Any, Optional
 
 from bs4 import BeautifulSoup
 
@@ -26,16 +24,13 @@ def _decode_base64(data: str) -> str:
     omit padding and use non-standard characters.
 
     Args:
-        data (str):
-            URL-safe base64-encoded string.
+        data: URL-safe base64-encoded string.
 
     Returns:
-        str:
-            Decoded UTF-8 text with replacement for invalid characters.
+        Decoded UTF-8 text with replacement for invalid characters.
 
     Raises:
-        MailIntakeParsingError:
-            If decoding fails.
+        MailIntakeParsingError: If decoding fails.
     """
     try:
         padded = data.replace("-", "+").replace("_", "/")
@@ -45,22 +40,19 @@ def _decode_base64(data: str) -> str:
         raise MailIntakeParsingError("Failed to decode message body") from exc
 
 
-def _extract_from_part(part: dict[str, Any]) -> str | None:
+def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
     """
     Extract text content from a single MIME part.
 
     Supports:
-
-    - `text/plain`
-    - `text/html` (converted to plain text)
+    - text/plain
+    - text/html (converted to plain text)
 
     Args:
-        part (dict[str, Any]):
-            MIME part dictionary from a provider payload.
+        part: MIME part dictionary from a provider payload.
 
     Returns:
-        str | None:
-            Extracted plain-text content, or `None` if unsupported or empty.
+        Extracted plain-text content, or None if unsupported or empty.
     """
     mime_type = part.get("mimeType")
     body = part.get("body", {})
@@ -82,24 +74,21 @@ def _extract_from_part(part: dict[str, Any]) -> str | None:
     return None
 
 
-def extract_body(payload: dict[str, Any]) -> str:
+def extract_body(payload: Dict[str, Any]) -> str:
     """
     Extract the best-effort message body from a Gmail payload.
 
     Priority:
-
-    1. `text/plain`
-    2. `text/html` (stripped to text)
+    1. text/plain
+    2. text/html (stripped to text)
     3. Single-part body
-    4. Empty string (if nothing usable found)
+    4. empty string (if nothing usable found)
 
     Args:
-        payload (dict[str, Any]):
-            Provider-native message payload dictionary.
+        payload: Provider-native message payload dictionary.
 
     Returns:
-        str:
-            Extracted plain-text message body.
+        Extracted plain-text message body.
     """
     if not payload:
         return ""

mail_intake/parsers/body.pyi

@@ -1,3 +1,3 @@
-from typing import Any
+from typing import Dict, Any
 
-def extract_body(payload: dict[str, Any]) -> str: ...
+def extract_body(payload: Dict[str, Any]) -> str: ...

mail_intake/parsers/headers.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Message header parsing utilities for Mail Intake.
 
 This module provides helper functions for normalizing and extracting
@@ -10,31 +8,25 @@ The functions here are intentionally simple and tolerant of malformed
 or incomplete header data.
 """
 
+from typing import Dict, List, Tuple, Optional
 
-def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]:
+
+def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
     """
     Convert a list of Gmail-style headers into a normalized dict.
 
+    Provider payloads (such as Gmail) typically represent headers as a list
+    of name/value mappings. This function normalizes them into a
+    case-insensitive dictionary keyed by lowercase header names.
+
     Args:
-        raw_headers (list[dict[str, str]]):
-            List of header dictionaries, each containing `name` and `value` keys.
+        raw_headers: List of header dictionaries, each containing
+            ``name`` and ``value`` keys.
 
     Returns:
-        dict[str, str]:
-            Dictionary mapping lowercase header names to stripped values.
-
-    Notes:
-        **Guarantees:**
-
-            - Provider payloads (such as Gmail) typically represent headers as a
-              list of name/value mappings.
-            - This function normalizes them into a case-insensitive dictionary
-              keyed by lowercase header names.
+        Dictionary mapping lowercase header names to stripped values.
 
     Example:
-        Typical usage:
-
-        ```python
         Input:
             [
                 {"name": "From", "value": "John Doe <john@example.com>"},
@@ -46,9 +38,8 @@ def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]:
                 "from": "John Doe <john@example.com>",
                 "subject": "Re: Interview Update",
             }
-        ```
     """
-    headers: dict[str, str] = {}
+    headers: Dict[str, str] = {}
 
     for header in raw_headers or []:
         name = header.get("name")
@@ -62,30 +53,26 @@ def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]:
     return headers
 
 
-def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]:
+def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]:
     """
     Extract sender email and optional display name from headers.
 
+    This function parses the ``From`` header and attempts to extract:
+    - Sender email address
+    - Optional human-readable display name
+
     Args:
-        headers (dict[str, str]):
-            Normalized header dictionary as returned by `parse_headers()`.
+        headers: Normalized header dictionary as returned by
+            :func:`parse_headers`.
 
     Returns:
-        tuple[str, str | None]:
-            A tuple `(email, name)` where `email` is the sender email address
-            and `name` is the display name, or `None` if unavailable.
+        A tuple ``(email, name)`` where:
+        - ``email`` is the sender email address
+        - ``name`` is the display name, or ``None`` if unavailable
 
-    Notes:
-        **Responsibilities:**
-
-            - This function parses the `From` header and attempts to extract
-              sender email address and optional human-readable display name.
-
-    Example:
-        Typical values:
-
-        - `"John Doe <john@example.com>"` -> `("john@example.com", "John Doe")`
-        - `"john@example.com"` -> `("john@example.com", None)`
+    Examples:
+        ``"John Doe <john@example.com>"`` → ``("john@example.com", "John Doe")``
+        ``"john@example.com"`` → ``("john@example.com", None)``
     """
     from_header = headers.get("from")
     if not from_header:

mail_intake/parsers/headers.pyi

@@ -1,2 +1,4 @@
-def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]: ...
-def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]: ...
+from typing import Dict, List, Tuple, Optional
+
+def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]: ...
+def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]: ...

mail_intake/parsers/subject.py

@@ -1,6 +1,4 @@
 """
-# Summary
-
 Subject line normalization utilities for Mail Intake.
 
 This module provides helper functions for normalizing email subject lines
@@ -12,36 +10,29 @@ meaning while removing common reply and forward prefixes.
 
 import re
 
+
 _PREFIX_RE = re.compile(r"^(re|fw|fwd)\s*:\s*", re.IGNORECASE)
-"""
-Regular expression matching common reply/forward subject prefixes.
-"""
+"""Regular expression matching common reply/forward subject prefixes."""
 
 
 def normalize_subject(subject: str) -> str:
     """
     Normalize an email subject for thread-level comparison.
 
+    Operations:
+    - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``
+    - Repeats prefix stripping to handle stacked prefixes
+    - Collapses excessive whitespace
+    - Preserves original casing (no lowercasing)
+
+    This function is intentionally conservative and avoids aggressive
+    transformations that could alter the semantic meaning of the subject.
+
     Args:
-        subject (str):
-            Raw subject line from a message header.
+        subject: Raw subject line from a message header.
 
     Returns:
-        str:
-            Normalized subject string suitable for thread grouping.
-
-    Notes:
-        **Responsibilities:**
-
-            - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.
-            - Repeats prefix stripping to handle stacked prefixes.
-            - Collapses excessive whitespace.
-            - Preserves original casing (no lowercasing).
-
-        **Guarantees:**
-
-            - This function is intentionally conservative and avoids aggressive
-              transformations that could alter the semantic meaning of the subject.
+        Normalized subject string suitable for thread grouping.
     """
     if not subject:
         return ""

mcp_docs/index.json

@@ -1,5 +1,5 @@
 {
-  "project": "Mail Intake",
+  "project": "mail_intake",
   "type": "docforge-model",
   "modules_count": 22,
   "source": "docforge"

mcp_docs/modules/mail_intake.adapters.base.json

@@ -0,0 +1,74 @@
+{
+  "module": "mail_intake.adapters.base",
+  "content": {
+    "path": "mail_intake.adapters.base",
+    "docstring": "Mail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
+    "objects": {
+      "ABC": {
+        "name": "ABC",
+        "kind": "alias",
+        "path": "mail_intake.adapters.base.ABC",
+        "signature": "<bound method Alias.signature of Alias('ABC', 'abc.ABC')>",
+        "docstring": null
+      },
+      "abstractmethod": {
+        "name": "abstractmethod",
+        "kind": "alias",
+        "path": "mail_intake.adapters.base.abstractmethod",
+        "signature": "<bound method Alias.signature of Alias('abstractmethod', 'abc.abstractmethod')>",
+        "docstring": null
+      },
+      "Iterator": {
+        "name": "Iterator",
+        "kind": "alias",
+        "path": "mail_intake.adapters.base.Iterator",
+        "signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
+        "docstring": null
+      },
+      "Dict": {
+        "name": "Dict",
+        "kind": "alias",
+        "path": "mail_intake.adapters.base.Dict",
+        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "mail_intake.adapters.base.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
+      "MailIntakeAdapter": {
+        "name": "MailIntakeAdapter",
+        "kind": "class",
+        "path": "mail_intake.adapters.base.MailIntakeAdapter",
+        "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 16, 76)>",
+        "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
+        "members": {
+          "iter_message_refs": {
+            "name": "iter_message_refs",
+            "kind": "function",
+            "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
+            "signature": "<bound method Function.signature of Function('iter_message_refs', 28, 49)>",
+            "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
+          },
+          "fetch_message": {
+            "name": "fetch_message",
+            "kind": "function",
+            "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
+            "signature": "<bound method Function.signature of Function('fetch_message', 51, 63)>",
+            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
+          },
+          "fetch_thread": {
+            "name": "fetch_thread",
+            "kind": "function",
+            "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
+            "signature": "<bound method Function.signature of Function('fetch_thread', 65, 76)>",
+            "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
+          }
+        }
+      }
+    }
+  }
+}

mcp_docs/modules/mail_intake.adapters.gmail.json

@@ -0,0 +1,134 @@
+{
+  "module": "mail_intake.adapters.gmail",
+  "content": {
+    "path": "mail_intake.adapters.gmail",
+    "docstring": "Gmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
+    "objects": {
+      "Iterator": {
+        "name": "Iterator",
+        "kind": "alias",
+        "path": "mail_intake.adapters.gmail.Iterator",
+        "signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
+        "docstring": null
+      },
+      "Dict": {
+        "name": "Dict",
+        "kind": "alias",
+        "path": "mail_intake.adapters.gmail.Dict",
+        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "mail_intake.adapters.gmail.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
+      "build": {
+        "name": "build",
+        "kind": "alias",
+        "path": "mail_intake.adapters.gmail.build",
+        "signature": "<bound method Alias.signature of Alias('build', 'googleapiclient.discovery.build')>",
+        "docstring": null
+      },
+      "HttpError": {
+        "name": "HttpError",
+        "kind": "alias",
+        "path": "mail_intake.adapters.gmail.HttpError",
+        "signature": "<bound method Alias.signature of Alias('HttpError', 'googleapiclient.errors.HttpError')>",
+        "docstring": null
+      },
+      "MailIntakeAdapter": {
+        "name": "MailIntakeAdapter",
+        "kind": "class",
+        "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
+        "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
+        "members": {
+          "iter_message_refs": {
+            "name": "iter_message_refs",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
+            "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
+            "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
+          },
+          "fetch_message": {
+            "name": "fetch_message",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
+            "signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
+            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
+          },
+          "fetch_thread": {
+            "name": "fetch_thread",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
+            "signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
+            "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
+          }
+        }
+      },
+      "MailIntakeAdapterError": {
+        "name": "MailIntakeAdapterError",
+        "kind": "class",
+        "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
+        "docstring": "Errors raised by mail provider adapters.\n\nRaised when a provider adapter encounters API errors,\ntransport failures, or invalid provider responses."
+      },
+      "MailIntakeAuthProvider": {
+        "name": "MailIntakeAuthProvider",
+        "kind": "class",
+        "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+        "members": {
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
+            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+          }
+        }
+      },
+      "MailIntakeGmailAdapter": {
+        "name": "MailIntakeGmailAdapter",
+        "kind": "class",
+        "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
+        "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 25, 172)>",
+        "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\nThis class is the ONLY place where:\n- googleapiclient is imported\n- Gmail REST semantics are known\n- .execute() is called\n\nDesign constraints:\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": {
+            "name": "service",
+            "kind": "attribute",
+            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
+            "signature": null,
+            "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n    Initialized Gmail API service instance.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail service cannot be initialized."
+          },
+          "iter_message_refs": {
+            "name": "iter_message_refs",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
+            "signature": "<bound method Function.signature of Function('iter_message_refs', 82, 122)>",
+            "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query: Gmail search query string.\n\nYields:\n    Dictionaries containing:\n    - ``message_id``: Gmail message ID\n    - ``thread_id``: Gmail thread ID\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          },
+          "fetch_message": {
+            "name": "fetch_message",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
+            "signature": "<bound method Function.signature of Function('fetch_message', 124, 147)>",
+            "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id: Gmail message identifier.\n\nReturns:\n    Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          },
+          "fetch_thread": {
+            "name": "fetch_thread",
+            "kind": "function",
+            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
+            "signature": "<bound method Function.signature of Function('fetch_thread', 149, 172)>",
+            "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id: Gmail thread identifier.\n\nReturns:\n    Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          }
+        }
+      }
+    }
+  }
+}

mcp_docs/modules/mail_intake.adapters.json

@@ -0,0 +1,284 @@
+{
+  "module": "mail_intake.adapters",
+  "content": {
+    "path": "mail_intake.adapters",
+    "docstring": "Mail provider adapter implementations for Mail Intake.\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n- Implement the `MailIntakeAdapter` interface\n- Encapsulate all provider-specific APIs and semantics\n- Perform read-only access to mail data\n- Return provider-native payloads without interpretation\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\nPublic adapters exported from this package are considered the supported\nintegration surface for mail providers.",
+    "objects": {
+      "MailIntakeAdapter": {
+        "name": "MailIntakeAdapter",
+        "kind": "class",
+        "path": "mail_intake.adapters.MailIntakeAdapter",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
+        "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
+        "members": {
+          "iter_message_refs": {
+            "name": "iter_message_refs",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
+            "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
+            "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
+          },
+          "fetch_message": {
+            "name": "fetch_message",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
+            "signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
+            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
+          },
+          "fetch_thread": {
+            "name": "fetch_thread",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
+            "signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
+            "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
+          }
+        }
+      },
+      "MailIntakeGmailAdapter": {
+        "name": "MailIntakeGmailAdapter",
+        "kind": "class",
+        "path": "mail_intake.adapters.MailIntakeGmailAdapter",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeGmailAdapter', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter')>",
+        "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\nThis class is the ONLY place where:\n- googleapiclient is imported\n- Gmail REST semantics are known\n- .execute() is called\n\nDesign constraints:\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": {
+            "name": "service",
+            "kind": "attribute",
+            "path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
+            "signature": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.service')>",
+            "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n    Initialized Gmail API service instance.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail service cannot be initialized."
+          },
+          "iter_message_refs": {
+            "name": "iter_message_refs",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs",
+            "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs')>",
+            "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query: Gmail search query string.\n\nYields:\n    Dictionaries containing:\n    - ``message_id``: Gmail message ID\n    - ``thread_id``: Gmail thread ID\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          },
+          "fetch_message": {
+            "name": "fetch_message",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
+            "signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message')>",
+            "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id: Gmail message identifier.\n\nReturns:\n    Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          },
+          "fetch_thread": {
+            "name": "fetch_thread",
+            "kind": "function",
+            "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
+            "signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread')>",
+            "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id: Gmail thread identifier.\n\nReturns:\n    Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+          }
+        }
+      },
+      "base": {
+        "name": "base",
+        "kind": "module",
+        "path": "mail_intake.adapters.base",
+        "signature": null,
+        "docstring": "Mail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
+        "members": {
+          "ABC": {
+            "name": "ABC",
+            "kind": "alias",
+            "path": "mail_intake.adapters.base.ABC",
+            "signature": "<bound method Alias.signature of Alias('ABC', 'abc.ABC')>",
+            "docstring": null
+          },
+          "abstractmethod": {
+            "name": "abstractmethod",
+            "kind": "alias",
+            "path": "mail_intake.adapters.base.abstractmethod",
+            "signature": "<bound method Alias.signature of Alias('abstractmethod', 'abc.abstractmethod')>",
+            "docstring": null
+          },
+          "Iterator": {
+            "name": "Iterator",
+            "kind": "alias",
+            "path": "mail_intake.adapters.base.Iterator",
+            "signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
+            "docstring": null
+          },
+          "Dict": {
+            "name": "Dict",
+            "kind": "alias",
+            "path": "mail_intake.adapters.base.Dict",
+            "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
+            "docstring": null
+          },
+          "Any": {
+            "name": "Any",
+            "kind": "alias",
+            "path": "mail_intake.adapters.base.Any",
+            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+            "docstring": null
+          },
+          "MailIntakeAdapter": {
+            "name": "MailIntakeAdapter",
+            "kind": "class",
+            "path": "mail_intake.adapters.base.MailIntakeAdapter",
+            "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 16, 76)>",
+            "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
+            "members": {
+              "iter_message_refs": {
+                "name": "iter_message_refs",
+                "kind": "function",
+                "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
+                "signature": "<bound method Function.signature of Function('iter_message_refs', 28, 49)>",
+                "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
+              },
+              "fetch_message": {
+                "name": "fetch_message",
+                "kind": "function",
+                "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
+                "signature": "<bound method Function.signature of Function('fetch_message', 51, 63)>",
+                "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
+              },
+              "fetch_thread": {
+                "name": "fetch_thread",
+                "kind": "function",
+                "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
+                "signature": "<bound method Function.signature of Function('fetch_thread', 65, 76)>",
+                "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
+              }
+            }
+          }
+        }
+      },
+      "gmail": {
+        "name": "gmail",
+        "kind": "module",
+        "path": "mail_intake.adapters.gmail",
+        "signature": null,
+        "docstring": "Gmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
+        "members": {
+          "Iterator": {
+            "name": "Iterator",
+            "kind": "alias",
+            "path": "mail_intake.adapters.gmail.Iterator",
+            "signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
+            "docstring": null
+          },
+          "Dict": {
+            "name": "Dict",
+            "kind": "alias",
+            "path": "mail_intake.adapters.gmail.Dict",
+            "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
+            "docstring": null
+          },
+          "Any": {
+            "name": "Any",
+            "kind": "alias",
+            "path": "mail_intake.adapters.gmail.Any",
+            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+            "docstring": null
+          },
+          "build": {
+            "name": "build",
+            "kind": "alias",
+            "path": "mail_intake.adapters.gmail.build",
+            "signature": "<bound method Alias.signature of Alias('build', 'googleapiclient.discovery.build')>",
+            "docstring": null
+          },
+          "HttpError": {
+            "name": "HttpError",
+            "kind": "alias",
+            "path": "mail_intake.adapters.gmail.HttpError",
+            "signature": "<bound method Alias.signature of Alias('HttpError', 'googleapiclient.errors.HttpError')>",
+            "docstring": null
+          },
+          "MailIntakeAdapter": {
+            "name": "MailIntakeAdapter",
+            "kind": "class",
+            "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
+            "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
+            "members": {
+              "iter_message_refs": {
+                "name": "iter_message_refs",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
+                "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
+                "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
+              },
+              "fetch_message": {
+                "name": "fetch_message",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
+                "signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
+                "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
+              },
+              "fetch_thread": {
+                "name": "fetch_thread",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
+                "signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
+                "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
+              }
+            }
+          },
+          "MailIntakeAdapterError": {
+            "name": "MailIntakeAdapterError",
+            "kind": "class",
+            "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
+            "docstring": "Errors raised by mail provider adapters.\n\nRaised when a provider adapter encounters API errors,\ntransport failures, or invalid provider responses."
+          },
+          "MailIntakeAuthProvider": {
+            "name": "MailIntakeAuthProvider",
+            "kind": "class",
+            "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+            "members": {
+              "get_credentials": {
+                "name": "get_credentials",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
+                "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+              }
+            }
+          },
+          "MailIntakeGmailAdapter": {
+            "name": "MailIntakeGmailAdapter",
+            "kind": "class",
+            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
+            "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 25, 172)>",
+            "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\nThis class is the ONLY place where:\n- googleapiclient is imported\n- Gmail REST semantics are known\n- .execute() is called\n\nDesign constraints:\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": {
+                "name": "service",
+                "kind": "attribute",
+                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
+                "signature": null,
+                "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n    Initialized Gmail API service instance.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail service cannot be initialized."
+              },
+              "iter_message_refs": {
+                "name": "iter_message_refs",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
+                "signature": "<bound method Function.signature of Function('iter_message_refs', 82, 122)>",
+                "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query: Gmail search query string.\n\nYields:\n    Dictionaries containing:\n    - ``message_id``: Gmail message ID\n    - ``thread_id``: Gmail thread ID\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+              },
+              "fetch_message": {
+                "name": "fetch_message",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
+                "signature": "<bound method Function.signature of Function('fetch_message', 124, 147)>",
+                "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id: Gmail message identifier.\n\nReturns:\n    Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+              },
+              "fetch_thread": {
+                "name": "fetch_thread",
+                "kind": "function",
+                "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
+                "signature": "<bound method Function.signature of Function('fetch_thread', 149, 172)>",
+                "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id: Gmail thread identifier.\n\nReturns:\n    Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

mcp_docs/modules/mail_intake.auth.base.json

@@ -0,0 +1,60 @@
+{
+  "module": "mail_intake.auth.base",
+  "content": {
+    "path": "mail_intake.auth.base",
+    "docstring": "Authentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
+    "objects": {
+      "ABC": {
+        "name": "ABC",
+        "kind": "alias",
+        "path": "mail_intake.auth.base.ABC",
+        "signature": "<bound method Alias.signature of Alias('ABC', 'abc.ABC')>",
+        "docstring": null
+      },
+      "abstractmethod": {
+        "name": "abstractmethod",
+        "kind": "alias",
+        "path": "mail_intake.auth.base.abstractmethod",
+        "signature": "<bound method Alias.signature of Alias('abstractmethod', 'abc.abstractmethod')>",
+        "docstring": null
+      },
+      "Generic": {
+        "name": "Generic",
+        "kind": "alias",
+        "path": "mail_intake.auth.base.Generic",
+        "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
+        "docstring": null
+      },
+      "TypeVar": {
+        "name": "TypeVar",
+        "kind": "alias",
+        "path": "mail_intake.auth.base.TypeVar",
+        "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
+        "docstring": null
+      },
+      "T": {
+        "name": "T",
+        "kind": "attribute",
+        "path": "mail_intake.auth.base.T",
+        "signature": null,
+        "docstring": null
+      },
+      "MailIntakeAuthProvider": {
+        "name": "MailIntakeAuthProvider",
+        "kind": "class",
+        "path": "mail_intake.auth.base.MailIntakeAuthProvider",
+        "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 18, 59)>",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+        "members": {
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
+            "signature": "<bound method Function.signature of Function('get_credentials', 37, 59)>",
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+          }
+        }
+      }
+    }
+  }
+}

mcp_docs/modules/mail_intake.auth.google.json

@@ -0,0 +1,148 @@
+{
+  "module": "mail_intake.auth.google",
+  "content": {
+    "path": "mail_intake.auth.google",
+    "docstring": "Google authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
+    "objects": {
+      "os": {
+        "name": "os",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.os",
+        "signature": "<bound method Alias.signature of Alias('os', 'os')>",
+        "docstring": null
+      },
+      "Sequence": {
+        "name": "Sequence",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.Sequence",
+        "signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
+        "docstring": null
+      },
+      "google": {
+        "name": "google",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.google",
+        "signature": "<bound method Alias.signature of Alias('google', 'google')>",
+        "docstring": null
+      },
+      "Request": {
+        "name": "Request",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.Request",
+        "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
+        "docstring": null
+      },
+      "InstalledAppFlow": {
+        "name": "InstalledAppFlow",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.InstalledAppFlow",
+        "signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
+        "docstring": null
+      },
+      "Credentials": {
+        "name": "Credentials",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.Credentials",
+        "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
+        "docstring": null
+      },
+      "MailIntakeAuthProvider": {
+        "name": "MailIntakeAuthProvider",
+        "kind": "class",
+        "path": "mail_intake.auth.google.MailIntakeAuthProvider",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+        "members": {
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
+            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+          }
+        }
+      },
+      "CredentialStore": {
+        "name": "CredentialStore",
+        "kind": "class",
+        "path": "mail_intake.auth.google.CredentialStore",
+        "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
+        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nThis interface separates *credential lifecycle management* from\n*credential storage mechanics*. Implementations are responsible\nonly for persistence concerns, while authentication providers\nretain full control over credential creation, validation, refresh,\nand revocation logic.\n\nThe 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.auth.google.CredentialStore.load",
+            "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
+            "docstring": "Load previously persisted credentials.\n\nImplementations should return ``None`` when no credentials are\npresent or when stored credentials cannot be successfully\ndecoded or deserialized.\n\nThe store must not attempt to validate, refresh, or otherwise\ninterpret the returned credentials.\n\nReturns:\n    An instance of type ``T`` if credentials are available and\n    loadable; otherwise ``None``."
+          },
+          "save": {
+            "name": "save",
+            "kind": "function",
+            "path": "mail_intake.auth.google.CredentialStore.save",
+            "signature": "<bound method Alias.signature of Alias('save', 'mail_intake.credentials.store.CredentialStore.save')>",
+            "docstring": "Persist credentials to the underlying storage backend.\n\nThis method is invoked when credentials are newly obtained or\nhave been refreshed and are known to be valid at the time of\npersistence.\n\nImplementations are responsible for:\n- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n\nArgs:\n    credentials:\n        The credential object to persist."
+          },
+          "clear": {
+            "name": "clear",
+            "kind": "function",
+            "path": "mail_intake.auth.google.CredentialStore.clear",
+            "signature": "<bound method Alias.signature of Alias('clear', 'mail_intake.credentials.store.CredentialStore.clear')>",
+            "docstring": "Remove any persisted credentials from the store.\n\nThis method is called when credentials are known to be invalid,\nrevoked, corrupted, or otherwise unusable, and must ensure that\nno stale authentication material remains accessible.\n\nImplementations should treat this operation as idempotent."
+          }
+        }
+      },
+      "MailIntakeAuthError": {
+        "name": "MailIntakeAuthError",
+        "kind": "class",
+        "path": "mail_intake.auth.google.MailIntakeAuthError",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
+        "docstring": "Authentication and credential-related failures.\n\nRaised when authentication providers are unable to acquire,\nrefresh, or persist valid credentials."
+      },
+      "MailIntakeGoogleAuth": {
+        "name": "MailIntakeGoogleAuth",
+        "kind": "class",
+        "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
+        "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 29, 125)>",
+        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nResponsibilities:\n- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n\nThis class is synchronous by design and maintains a minimal internal state.",
+        "members": {
+          "credentials_path": {
+            "name": "credentials_path",
+            "kind": "attribute",
+            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path",
+            "signature": null,
+            "docstring": null
+          },
+          "store": {
+            "name": "store",
+            "kind": "attribute",
+            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.store",
+            "signature": null,
+            "docstring": null
+          },
+          "scopes": {
+            "name": "scopes",
+            "kind": "attribute",
+            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.scopes",
+            "signature": null,
+            "docstring": null
+          },
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
+            "signature": "<bound method Function.signature of Function('get_credentials', 70, 125)>",
+            "docstring": "Retrieve valid Google OAuth credentials.\n\nThis method attempts to:\n1. Load cached credentials from the configured credential store\n2. Refresh expired credentials when possible\n3. Perform an interactive OAuth login as a fallback\n4. Persist valid credentials for future use\n\nReturns:\n    A ``google.oauth2.credentials.Credentials`` instance suitable\n    for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError: If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication."
+          }
+        }
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "mail_intake.auth.google.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      }
+    }
+  }
+}

mcp_docs/modules/mail_intake.auth.json

@@ -0,0 +1,270 @@
+{
+  "module": "mail_intake.auth",
+  "content": {
+    "path": "mail_intake.auth",
+    "docstring": "Authentication provider implementations for Mail Intake.\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n- A stable, provider-agnostic authentication contract\n- Concrete authentication providers for supported platforms\n\nAuthentication providers:\n- Are responsible for credential acquisition and lifecycle management\n- Are intentionally decoupled from adapter logic\n- May be extended by users to support additional providers\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.",
+    "objects": {
+      "MailIntakeAuthProvider": {
+        "name": "MailIntakeAuthProvider",
+        "kind": "class",
+        "path": "mail_intake.auth.MailIntakeAuthProvider",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+        "members": {
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials",
+            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+          }
+        }
+      },
+      "MailIntakeGoogleAuth": {
+        "name": "MailIntakeGoogleAuth",
+        "kind": "class",
+        "path": "mail_intake.auth.MailIntakeGoogleAuth",
+        "signature": "<bound method Alias.signature of Alias('MailIntakeGoogleAuth', 'mail_intake.auth.google.MailIntakeGoogleAuth')>",
+        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nResponsibilities:\n- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n\nThis class is synchronous by design and maintains a minimal internal state.",
+        "members": {
+          "credentials_path": {
+            "name": "credentials_path",
+            "kind": "attribute",
+            "path": "mail_intake.auth.MailIntakeGoogleAuth.credentials_path",
+            "signature": "<bound method Alias.signature of Alias('credentials_path', 'mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path')>",
+            "docstring": null
+          },
+          "store": {
+            "name": "store",
+            "kind": "attribute",
+            "path": "mail_intake.auth.MailIntakeGoogleAuth.store",
+            "signature": "<bound method Alias.signature of Alias('store', 'mail_intake.auth.google.MailIntakeGoogleAuth.store')>",
+            "docstring": null
+          },
+          "scopes": {
+            "name": "scopes",
+            "kind": "attribute",
+            "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes",
+            "signature": "<bound method Alias.signature of Alias('scopes', 'mail_intake.auth.google.MailIntakeGoogleAuth.scopes')>",
+            "docstring": null
+          },
+          "get_credentials": {
+            "name": "get_credentials",
+            "kind": "function",
+            "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
+            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials')>",
+            "docstring": "Retrieve valid Google OAuth credentials.\n\nThis method attempts to:\n1. Load cached credentials from the configured credential store\n2. Refresh expired credentials when possible\n3. Perform an interactive OAuth login as a fallback\n4. Persist valid credentials for future use\n\nReturns:\n    A ``google.oauth2.credentials.Credentials`` instance suitable\n    for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError: If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication."
+          }
+        }
+      },
+      "base": {
+        "name": "base",
+        "kind": "module",
+        "path": "mail_intake.auth.base",
+        "signature": null,
+        "docstring": "Authentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
+        "members": {
+          "ABC": {
+            "name": "ABC",
+            "kind": "alias",
+            "path": "mail_intake.auth.base.ABC",
+            "signature": "<bound method Alias.signature of Alias('ABC', 'abc.ABC')>",
+            "docstring": null
+          },
+          "abstractmethod": {
+            "name": "abstractmethod",
+            "kind": "alias",
+            "path": "mail_intake.auth.base.abstractmethod",
+            "signature": "<bound method Alias.signature of Alias('abstractmethod', 'abc.abstractmethod')>",
+            "docstring": null
+          },
+          "Generic": {
+            "name": "Generic",
+            "kind": "alias",
+            "path": "mail_intake.auth.base.Generic",
+            "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
+            "docstring": null
+          },
+          "TypeVar": {
+            "name": "TypeVar",
+            "kind": "alias",
+            "path": "mail_intake.auth.base.TypeVar",
+            "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
+            "docstring": null
+          },
+          "T": {
+            "name": "T",
+            "kind": "attribute",
+            "path": "mail_intake.auth.base.T",
+            "signature": null,
+            "docstring": null
+          },
+          "MailIntakeAuthProvider": {
+            "name": "MailIntakeAuthProvider",
+            "kind": "class",
+            "path": "mail_intake.auth.base.MailIntakeAuthProvider",
+            "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 18, 59)>",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+            "members": {
+              "get_credentials": {
+                "name": "get_credentials",
+                "kind": "function",
+                "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
+                "signature": "<bound method Function.signature of Function('get_credentials', 37, 59)>",
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+              }
+            }
+          }
+        }
+      },
+      "google": {
+        "name": "google",
+        "kind": "module",
+        "path": "mail_intake.auth.google",
+        "signature": null,
+        "docstring": "Google authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
+        "members": {
+          "os": {
+            "name": "os",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.os",
+            "signature": "<bound method Alias.signature of Alias('os', 'os')>",
+            "docstring": null
+          },
+          "Sequence": {
+            "name": "Sequence",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.Sequence",
+            "signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
+            "docstring": null
+          },
+          "google": {
+            "name": "google",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.google",
+            "signature": "<bound method Alias.signature of Alias('google', 'google')>",
+            "docstring": null
+          },
+          "Request": {
+            "name": "Request",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.Request",
+            "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
+            "docstring": null
+          },
+          "InstalledAppFlow": {
+            "name": "InstalledAppFlow",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.InstalledAppFlow",
+            "signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
+            "docstring": null
+          },
+          "Credentials": {
+            "name": "Credentials",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.Credentials",
+            "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
+            "docstring": null
+          },
+          "MailIntakeAuthProvider": {
+            "name": "MailIntakeAuthProvider",
+            "kind": "class",
+            "path": "mail_intake.auth.google.MailIntakeAuthProvider",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
+            "members": {
+              "get_credentials": {
+                "name": "get_credentials",
+                "kind": "function",
+                "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
+                "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
+              }
+            }
+          },
+          "CredentialStore": {
+            "name": "CredentialStore",
+            "kind": "class",
+            "path": "mail_intake.auth.google.CredentialStore",
+            "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
+            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nThis interface separates *credential lifecycle management* from\n*credential storage mechanics*. Implementations are responsible\nonly for persistence concerns, while authentication providers\nretain full control over credential creation, validation, refresh,\nand revocation logic.\n\nThe 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.auth.google.CredentialStore.load",
+                "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
+                "docstring": "Load previously persisted credentials.\n\nImplementations should return ``None`` when no credentials are\npresent or when stored credentials cannot be successfully\ndecoded or deserialized.\n\nThe store must not attempt to validate, refresh, or otherwise\ninterpret the returned credentials.\n\nReturns:\n    An instance of type ``T`` if credentials are available and\n    loadable; otherwise ``None``."
+              },
+              "save": {
+                "name": "save",
+                "kind": "function",
+                "path": "mail_intake.auth.google.CredentialStore.save",
+                "signature": "<bound method Alias.signature of Alias('save', 'mail_intake.credentials.store.CredentialStore.save')>",
+                "docstring": "Persist credentials to the underlying storage backend.\n\nThis method is invoked when credentials are newly obtained or\nhave been refreshed and are known to be valid at the time of\npersistence.\n\nImplementations are responsible for:\n- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n\nArgs:\n    credentials:\n        The credential object to persist."
+              },
+              "clear": {
+                "name": "clear",
+                "kind": "function",
+                "path": "mail_intake.auth.google.CredentialStore.clear",
+                "signature": "<bound method Alias.signature of Alias('clear', 'mail_intake.credentials.store.CredentialStore.clear')>",
+                "docstring": "Remove any persisted credentials from the store.\n\nThis method is called when credentials are known to be invalid,\nrevoked, corrupted, or otherwise unusable, and must ensure that\nno stale authentication material remains accessible.\n\nImplementations should treat this operation as idempotent."
+              }
+            }
+          },
+          "MailIntakeAuthError": {
+            "name": "MailIntakeAuthError",
+            "kind": "class",
+            "path": "mail_intake.auth.google.MailIntakeAuthError",
+            "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
+            "docstring": "Authentication and credential-related failures.\n\nRaised when authentication providers are unable to acquire,\nrefresh, or persist valid credentials."
+          },
+          "MailIntakeGoogleAuth": {
+            "name": "MailIntakeGoogleAuth",
+            "kind": "class",
+            "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
+            "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 29, 125)>",
+            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nResponsibilities:\n- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n\nThis class is synchronous by design and maintains a minimal internal state.",
+            "members": {
+              "credentials_path": {
+                "name": "credentials_path",
+                "kind": "attribute",
+                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path",
+                "signature": null,
+                "docstring": null
+              },
+              "store": {
+                "name": "store",
+                "kind": "attribute",
+                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.store",
+                "signature": null,
+                "docstring": null
+              },
+              "scopes": {
+                "name": "scopes",
+                "kind": "attribute",
+                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.scopes",
+                "signature": null,
+                "docstring": null
+              },
+              "get_credentials": {
+                "name": "get_credentials",
+                "kind": "function",
+                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
+                "signature": "<bound method Function.signature of Function('get_credentials', 70, 125)>",
+                "docstring": "Retrieve valid Google OAuth credentials.\n\nThis method attempts to:\n1. Load cached credentials from the configured credential store\n2. Refresh expired credentials when possible\n3. Perform an interactive OAuth login as a fallback\n4. Persist valid credentials for future use\n\nReturns:\n    A ``google.oauth2.credentials.Credentials`` instance suitable\n    for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError: If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication."
+              }
+            }
+          },
+          "Any": {
+            "name": "Any",
+            "kind": "alias",
+            "path": "mail_intake.auth.google.Any",
+            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+            "docstring": null
+          }
+        }
+      }
+    }
+  }
+}