diff --git a/.gitignore b/.gitignore index 05c9968..2209baf 100644 --- a/.gitignore +++ b/.gitignore @@ -38,6 +38,7 @@ Thumbs.db *.swo *~ *.tmp +site # Credentials client_secret_*.json diff --git a/docforge.nav.yml b/docforge.nav.yml new file mode 100644 index 0000000..9438143 --- /dev/null +++ b/docforge.nav.yml @@ -0,0 +1,29 @@ +home: mail_intake/index.md +groups: + Core API: + - mail_intake/ingestion/index.md + - mail_intake/ingestion/reader.md + Domain Models: + - mail_intake/models/index.md + - mail_intake/models/message.md + - mail_intake/models/thread.md + Provider Adapters: + - mail_intake/adapters/index.md + - mail_intake/adapters/base.md + - mail_intake/adapters/gmail.md + Authentication & Storage: + - 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: + - mail_intake/parsers/index.md + - mail_intake/parsers/body.md + - mail_intake/parsers/headers.md + - mail_intake/parsers/subject.md + Configuration & Errors: + - mail_intake/config.md + - mail_intake/exceptions.md diff --git a/mail_intake/__init__.py b/mail_intake/__init__.py index e46a183..ae09028 100644 --- a/mail_intake/__init__.py +++ b/mail_intake/__init__.py @@ -114,6 +114,27 @@ Design Guarantees 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. """ diff --git a/mail_intake/__init__.pyi b/mail_intake/__init__.pyi new file mode 100644 index 0000000..dcf3ed8 --- /dev/null +++ b/mail_intake/__init__.pyi @@ -0,0 +1,17 @@ +from . import ingestion +from . import adapters +from . import auth +from . import credentials +from . import models +from . import config +from . import exceptions + +__all__ = [ + "ingestion", + "adapters", + "auth", + "credentials", + "models", + "config", + "exceptions", +] diff --git a/mail_intake/adapters/__init__.pyi b/mail_intake/adapters/__init__.pyi new file mode 100644 index 0000000..9110404 --- /dev/null +++ b/mail_intake/adapters/__init__.pyi @@ -0,0 +1,4 @@ +from .base import MailIntakeAdapter +from .gmail import MailIntakeGmailAdapter + +__all__ = ["MailIntakeAdapter", "MailIntakeGmailAdapter"] diff --git a/mail_intake/adapters/base.pyi b/mail_intake/adapters/base.pyi new file mode 100644 index 0000000..8cdcbd7 --- /dev/null +++ b/mail_intake/adapters/base.pyi @@ -0,0 +1,10 @@ +from abc import ABC, abstractmethod +from typing import Iterator, Dict, Any + +class MailIntakeAdapter(ABC): + @abstractmethod + def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ... + @abstractmethod + def fetch_message(self, message_id: str) -> Dict[str, Any]: ... + @abstractmethod + def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ... diff --git a/mail_intake/adapters/gmail.pyi b/mail_intake/adapters/gmail.pyi new file mode 100644 index 0000000..04204e7 --- /dev/null +++ b/mail_intake/adapters/gmail.pyi @@ -0,0 +1,11 @@ +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, 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]: ... diff --git a/mail_intake/auth/__init__.pyi b/mail_intake/auth/__init__.pyi new file mode 100644 index 0000000..27e866e --- /dev/null +++ b/mail_intake/auth/__init__.pyi @@ -0,0 +1,4 @@ +from .base import MailIntakeAuthProvider +from .google import MailIntakeGoogleAuth + +__all__ = ["MailIntakeAuthProvider", "MailIntakeGoogleAuth"] diff --git a/mail_intake/auth/base.pyi b/mail_intake/auth/base.pyi new file mode 100644 index 0000000..705427d --- /dev/null +++ b/mail_intake/auth/base.pyi @@ -0,0 +1,8 @@ +from abc import ABC, abstractmethod +from typing import Generic, TypeVar + +T = TypeVar("T") + +class MailIntakeAuthProvider(ABC, Generic[T]): + @abstractmethod + def get_credentials(self) -> T: ... diff --git a/mail_intake/auth/google.pyi b/mail_intake/auth/google.pyi new file mode 100644 index 0000000..57f16df --- /dev/null +++ b/mail_intake/auth/google.pyi @@ -0,0 +1,7 @@ +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 get_credentials(self) -> Any: ... diff --git a/mail_intake/config.pyi b/mail_intake/config.pyi new file mode 100644 index 0000000..a484b2c --- /dev/null +++ b/mail_intake/config.pyi @@ -0,0 +1,9 @@ +from typing import Optional + +class MailIntakeConfig: + provider: str + user_id: str + readonly: bool + 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: ... diff --git a/mail_intake/credentials/__init__.pyi b/mail_intake/credentials/__init__.pyi new file mode 100644 index 0000000..67256d1 --- /dev/null +++ b/mail_intake/credentials/__init__.pyi @@ -0,0 +1,5 @@ +from .store import CredentialStore +from .pickle import PickleCredentialStore +from .redis import RedisCredentialStore + +__all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"] diff --git a/mail_intake/credentials/pickle.pyi b/mail_intake/credentials/pickle.pyi new file mode 100644 index 0000000..ea6fa5c --- /dev/null +++ b/mail_intake/credentials/pickle.pyi @@ -0,0 +1,11 @@ +from typing import Optional, TypeVar +from .store import CredentialStore + +T = TypeVar("T") + +class PickleCredentialStore(CredentialStore[T]): + path: str + def __init__(self, path: str) -> None: ... + def load(self) -> Optional[T]: ... + def save(self, credentials: T) -> None: ... + def clear(self) -> None: ... diff --git a/mail_intake/credentials/redis.pyi b/mail_intake/credentials/redis.pyi new file mode 100644 index 0000000..52dcdf0 --- /dev/null +++ b/mail_intake/credentials/redis.pyi @@ -0,0 +1,15 @@ +from typing import Optional, TypeVar, Callable, Any +from .store import CredentialStore + +T = TypeVar("T") + +class RedisCredentialStore(CredentialStore[T]): + redis: Any + key: str + serialize: Callable[[T], bytes] + deserialize: Callable[[bytes], T] + 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: ... diff --git a/mail_intake/credentials/store.py b/mail_intake/credentials/store.py index 92e2af7..4ba5a83 100644 --- a/mail_intake/credentials/store.py +++ b/mail_intake/credentials/store.py @@ -39,12 +39,6 @@ class CredentialStore(ABC, Generic[T]): - The concrete credential type being stored - The serialization format used to persist credentials - The underlying storage backend or durability guarantees - - Type Parameters: - T: - The concrete credential type managed by the store. This may - represent OAuth credentials, API tokens, session objects, - or any other authentication material. """ @abstractmethod diff --git a/mail_intake/credentials/store.pyi b/mail_intake/credentials/store.pyi new file mode 100644 index 0000000..4798ca1 --- /dev/null +++ b/mail_intake/credentials/store.pyi @@ -0,0 +1,12 @@ +from abc import ABC, abstractmethod +from typing import Generic, Optional, TypeVar + +T = TypeVar("T") + +class CredentialStore(ABC, Generic[T]): + @abstractmethod + def load(self) -> Optional[T]: ... + @abstractmethod + def save(self, credentials: T) -> None: ... + @abstractmethod + def clear(self) -> None: ... diff --git a/mail_intake/exceptions.pyi b/mail_intake/exceptions.pyi new file mode 100644 index 0000000..bbcc0e9 --- /dev/null +++ b/mail_intake/exceptions.pyi @@ -0,0 +1,4 @@ +class MailIntakeError(Exception): ... +class MailIntakeAuthError(MailIntakeError): ... +class MailIntakeAdapterError(MailIntakeError): ... +class MailIntakeParsingError(MailIntakeError): ... diff --git a/mail_intake/ingestion/__init__.pyi b/mail_intake/ingestion/__init__.pyi new file mode 100644 index 0000000..1138b49 --- /dev/null +++ b/mail_intake/ingestion/__init__.pyi @@ -0,0 +1,3 @@ +from .reader import MailIntakeReader + +__all__ = ["MailIntakeReader"] diff --git a/mail_intake/ingestion/reader.pyi b/mail_intake/ingestion/reader.pyi new file mode 100644 index 0000000..b38852e --- /dev/null +++ b/mail_intake/ingestion/reader.pyi @@ -0,0 +1,10 @@ +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 + +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: ... diff --git a/mail_intake/models/__init__.pyi b/mail_intake/models/__init__.pyi new file mode 100644 index 0000000..b6c1898 --- /dev/null +++ b/mail_intake/models/__init__.pyi @@ -0,0 +1,4 @@ +from .message import MailIntakeMessage +from .thread import MailIntakeThread + +__all__ = ["MailIntakeMessage", "MailIntakeThread"] diff --git a/mail_intake/models/message.pyi b/mail_intake/models/message.pyi new file mode 100644 index 0000000..1b717d0 --- /dev/null +++ b/mail_intake/models/message.pyi @@ -0,0 +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: 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: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str]) -> None: ... diff --git a/mail_intake/models/thread.pyi b/mail_intake/models/thread.pyi new file mode 100644 index 0000000..0fe0541 --- /dev/null +++ b/mail_intake/models/thread.pyi @@ -0,0 +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: 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: ... diff --git a/mail_intake/parsers/__init__.pyi b/mail_intake/parsers/__init__.pyi new file mode 100644 index 0000000..0238a34 --- /dev/null +++ b/mail_intake/parsers/__init__.pyi @@ -0,0 +1,5 @@ +from .body import extract_body +from .headers import parse_headers, extract_sender +from .subject import normalize_subject + +__all__ = ["extract_body", "parse_headers", "extract_sender", "normalize_subject"] diff --git a/mail_intake/parsers/body.pyi b/mail_intake/parsers/body.pyi new file mode 100644 index 0000000..f13004f --- /dev/null +++ b/mail_intake/parsers/body.pyi @@ -0,0 +1,3 @@ +from typing import Dict, Any + +def extract_body(payload: Dict[str, Any]) -> str: ... diff --git a/mail_intake/parsers/headers.pyi b/mail_intake/parsers/headers.pyi new file mode 100644 index 0000000..f819ae7 --- /dev/null +++ b/mail_intake/parsers/headers.pyi @@ -0,0 +1,4 @@ +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]]: ... diff --git a/mail_intake/parsers/subject.pyi b/mail_intake/parsers/subject.pyi new file mode 100644 index 0000000..2169f09 --- /dev/null +++ b/mail_intake/parsers/subject.pyi @@ -0,0 +1 @@ +def normalize_subject(subject: str) -> str: ... diff --git a/manage_docs.py b/manage_docs.py deleted file mode 100644 index 91a44f8..0000000 --- a/manage_docs.py +++ /dev/null @@ -1,159 +0,0 @@ -""" -MkDocs documentation management CLI. - -This script provides a proper CLI interface to: -- Generate MkDocs Markdown files with mkdocstrings directives -- Build the documentation site -- Serve the documentation site locally - -All operations are performed by calling MkDocs as a Python library -(no shell command invocation). - -Requirements: -- mkdocs -- mkdocs-material -- mkdocstrings[python] - -Usage: - python manage_docs.py generate - python manage_docs.py build - python manage_docs.py serve - -Optional flags: - --docs-dir PATH Path to docs directory (default: ./docs) - --package-root NAME Root Python package name (default: mail_intake) -""" - -from __future__ import annotations - -import argparse -from pathlib import Path - -from mkdocs.commands import build as mkdocs_build -from mkdocs.commands import serve as mkdocs_serve -from mkdocs.config import load_config - - -PROJECT_ROOT = Path(__file__).resolve().parent -DEFAULT_DOCS_DIR = PROJECT_ROOT / "docs" -DEFAULT_PACKAGE_ROOT = "mail_intake" -MKDOCS_YML = PROJECT_ROOT / "mkdocs.yml" - - -def generate_docs_from_nav( - project_root: Path, - docs_root: Path, - package_root: str, -) -> None: - """ - Create and populate MkDocs Markdown files with mkdocstrings directives. - - This function: - - Walks the Python package structure - - Mirrors it under the docs directory - - Creates missing .md files - - Creates index.md for packages (__init__.py) - - Overwrites content with ::: package.module - - Examples: - mail_intake/__init__.py -> docs/mail_intake/index.md - mail_intake/config.py -> docs/mail_intake/config.md - mail_intake/adapters/__init__.py -> docs/mail_intake/adapters/index.md - mail_intake/adapters/base.py -> docs/mail_intake/adapters/base.md - """ - - package_dir = project_root / package_root - if not package_dir.exists(): - raise FileNotFoundError(f"Package not found: {package_dir}") - - docs_root.mkdir(parents=True, exist_ok=True) - - for py_file in package_dir.rglob("*.py"): - rel = py_file.relative_to(project_root) - - if py_file.name == "__init__.py": - # Package → index.md - module_path = ".".join(rel.parent.parts) - md_path = docs_root / rel.parent / "index.md" - title = rel.parent.name.replace("_", " ").title() - else: - # Regular module → .md - module_path = ".".join(rel.with_suffix("").parts) - md_path = docs_root / rel.with_suffix(".md") - title = md_path.stem.replace("_", " ").title() - - md_path.parent.mkdir(parents=True, exist_ok=True) - - content = f"""# {title} - -::: {module_path} -""" - - md_path.write_text(content, encoding="utf-8") - - -def load_mkdocs_config(): - if not MKDOCS_YML.exists(): - raise FileNotFoundError("mkdocs.yml not found at project root") - return load_config(str(MKDOCS_YML)) - - -def cmd_generate(args: argparse.Namespace) -> None: - generate_docs_from_nav( - project_root=PROJECT_ROOT, - docs_root=args.docs_dir, - package_root=args.package_root, - ) - - -def cmd_build(_: argparse.Namespace) -> None: - config = load_mkdocs_config() - mkdocs_build.build(config) - - -def cmd_serve(_: argparse.Namespace) -> None: - mkdocs_serve.serve( - config_file=str(MKDOCS_YML) - ) - -def main() -> None: - parser = argparse.ArgumentParser( - prog="manage_docs.py", - description="Manage MkDocs documentation for the project", - ) - - parser.add_argument( - "--docs-dir", - type=Path, - default=DEFAULT_DOCS_DIR, - help="Path to the docs directory", - ) - parser.add_argument( - "--package-root", - default=DEFAULT_PACKAGE_ROOT, - help="Root Python package name", - ) - - subparsers = parser.add_subparsers(dest="command", required=True) - - subparsers.add_parser( - "generate", - help="Generate Markdown files with mkdocstrings directives", - ).set_defaults(func=cmd_generate) - - subparsers.add_parser( - "build", - help="Build the MkDocs site", - ).set_defaults(func=cmd_build) - - subparsers.add_parser( - "serve", - help="Serve the MkDocs site locally", - ).set_defaults(func=cmd_serve) - - args = parser.parse_args() - args.func(args) - - -if __name__ == "__main__": - main() diff --git a/mcp_docs/index.json b/mcp_docs/index.json new file mode 100644 index 0000000..d4d506d --- /dev/null +++ b/mcp_docs/index.json @@ -0,0 +1,6 @@ +{ + "project": "mail_intake", + "type": "docforge-model", + "modules_count": 22, + "source": "docforge" +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.adapters.base.json b/mcp_docs/modules/mail_intake.adapters.base.json new file mode 100644 index 0000000..7e1a96c --- /dev/null +++ b/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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.adapters.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.adapters.base.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.base.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.base.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.base.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.adapters.gmail.json b/mcp_docs/modules/mail_intake.adapters.gmail.json new file mode 100644 index 0000000..bfd85b8 --- /dev/null +++ b/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": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Any", + "signature": "", + "docstring": null + }, + "build": { + "name": "build", + "kind": "alias", + "path": "mail_intake.adapters.gmail.build", + "signature": "", + "docstring": null + }, + "HttpError": { + "name": "HttpError", + "kind": "alias", + "path": "mail_intake.adapters.gmail.HttpError", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.adapters.json b/mcp_docs/modules/mail_intake.adapters.json new file mode 100644 index 0000000..495fda7 --- /dev/null +++ b/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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.adapters.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.adapters.base.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.base.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.base.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.base.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Any", + "signature": "", + "docstring": null + }, + "build": { + "name": "build", + "kind": "alias", + "path": "mail_intake.adapters.gmail.build", + "signature": "", + "docstring": null + }, + "HttpError": { + "name": "HttpError", + "kind": "alias", + "path": "mail_intake.adapters.gmail.HttpError", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.auth.base.json b/mcp_docs/modules/mail_intake.auth.base.json new file mode 100644 index 0000000..441e364 --- /dev/null +++ b/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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.auth.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.auth.base.Generic", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.auth.base.TypeVar", + "signature": "", + "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": "", + "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": "", + "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." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.auth.google.json b/mcp_docs/modules/mail_intake.auth.google.json new file mode 100644 index 0000000..5c8bee9 --- /dev/null +++ b/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": "", + "docstring": null + }, + "Sequence": { + "name": "Sequence", + "kind": "alias", + "path": "mail_intake.auth.google.Sequence", + "signature": "", + "docstring": null + }, + "google": { + "name": "google", + "kind": "alias", + "path": "mail_intake.auth.google.google", + "signature": "", + "docstring": null + }, + "Request": { + "name": "Request", + "kind": "alias", + "path": "mail_intake.auth.google.Request", + "signature": "", + "docstring": null + }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, + "Credentials": { + "name": "Credentials", + "kind": "alias", + "path": "mail_intake.auth.google.Credentials", + "signature": "", + "docstring": null + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.auth.google.MailIntakeAuthProvider", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.auth.json b/mcp_docs/modules/mail_intake.auth.json new file mode 100644 index 0000000..dd559e1 --- /dev/null +++ b/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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "store": { + "name": "store", + "kind": "attribute", + "path": "mail_intake.auth.MailIntakeGoogleAuth.store", + "signature": "", + "docstring": null + }, + "scopes": { + "name": "scopes", + "kind": "attribute", + "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes", + "signature": "", + "docstring": null + }, + "get_credentials": { + "name": "get_credentials", + "kind": "function", + "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials", + "signature": "", + "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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.auth.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.auth.base.Generic", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.auth.base.TypeVar", + "signature": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "Sequence": { + "name": "Sequence", + "kind": "alias", + "path": "mail_intake.auth.google.Sequence", + "signature": "", + "docstring": null + }, + "google": { + "name": "google", + "kind": "alias", + "path": "mail_intake.auth.google.google", + "signature": "", + "docstring": null + }, + "Request": { + "name": "Request", + "kind": "alias", + "path": "mail_intake.auth.google.Request", + "signature": "", + "docstring": null + }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, + "Credentials": { + "name": "Credentials", + "kind": "alias", + "path": "mail_intake.auth.google.Credentials", + "signature": "", + "docstring": null + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.auth.google.MailIntakeAuthProvider", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.config.json b/mcp_docs/modules/mail_intake.config.json new file mode 100644 index 0000000..f36cdb7 --- /dev/null +++ b/mcp_docs/modules/mail_intake.config.json @@ -0,0 +1,67 @@ +{ + "module": "mail_intake.config", + "content": { + "path": "mail_intake.config", + "docstring": "Global configuration models for Mail Intake.\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.", + "objects": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.config.dataclass", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.config.Optional", + "signature": "", + "docstring": null + }, + "MailIntakeConfig": { + "name": "MailIntakeConfig", + "kind": "class", + "path": "mail_intake.config.MailIntakeConfig", + "signature": "", + "docstring": "Global configuration for mail-intake.\n\nThis configuration is intentionally explicit and immutable.\nNo implicit environment reads or global state.\n\nDesign principles:\n- Immutable once constructed\n- Explicit configuration over implicit defaults\n- No direct environment or filesystem access\n\nThis model is safe to pass across layers and suitable for serialization.", + "members": { + "provider": { + "name": "provider", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.provider", + "signature": null, + "docstring": "Identifier of the mail provider to use (e.g., ``\"gmail\"``)." + }, + "user_id": { + "name": "user_id", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.user_id", + "signature": null, + "docstring": "Provider-specific user identifier. Defaults to the authenticated user." + }, + "readonly": { + "name": "readonly", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.readonly", + "signature": null, + "docstring": "Whether ingestion should operate in read-only mode." + }, + "credentials_path": { + "name": "credentials_path", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.credentials_path", + "signature": null, + "docstring": "Optional path to provider credentials configuration." + }, + "token_path": { + "name": "token_path", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.token_path", + "signature": null, + "docstring": "Optional path to persisted authentication tokens." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.credentials.json b/mcp_docs/modules/mail_intake.credentials.json new file mode 100644 index 0000000..1fca9da --- /dev/null +++ b/mcp_docs/modules/mail_intake.credentials.json @@ -0,0 +1,465 @@ +{ + "module": "mail_intake.credentials", + "content": { + "path": "mail_intake.credentials", + "docstring": "Credential 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- 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.", + "objects": { + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.CredentialStore", + "signature": "", + "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.credentials.CredentialStore.load", + "signature": "", + "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.credentials.CredentialStore.save", + "signature": "", + "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.credentials.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "PickleCredentialStore": { + "name": "PickleCredentialStore", + "kind": "class", + "path": "mail_intake.credentials.PickleCredentialStore", + "signature": "", + "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\nThis implementation:\n- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n\nCredential lifecycle management, validation, and refresh logic are\nexplicitly out of scope for this class.", + "members": { + "path": { + "name": "path", + "kind": "attribute", + "path": "mail_intake.credentials.PickleCredentialStore.path", + "signature": "", + "docstring": null + }, + "load": { + "name": "load", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.load", + "signature": "", + "docstring": "Load credentials from the local filesystem.\n\nIf the credential file does not exist or cannot be successfully\ndeserialized, this method returns ``None``.\n\nThe store does not attempt to validate or interpret the returned\ncredentials.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to the local filesystem.\n\nAny previously stored credentials at the configured path are\noverwritten.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.clear", + "signature": "", + "docstring": "Remove persisted credentials from the local filesystem.\n\nThis method deletes the credential file if it exists and should\nbe treated as an idempotent operation." + } + } + }, + "RedisCredentialStore": { + "name": "RedisCredentialStore", + "kind": "class", + "path": "mail_intake.credentials.RedisCredentialStore", + "signature": "", + "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nThe store is intentionally generic and delegates all serialization\nconcerns to caller-provided functions. This avoids unsafe mechanisms\nsuch as pickle and allows credential formats to be explicitly\ncontrolled and audited.\n\nThis class is responsible only for persistence and retrieval.\nIt does not interpret, validate, refresh, or otherwise manage\nthe lifecycle of the credentials being stored.", + "members": { + "redis": { + "name": "redis", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.redis", + "signature": "", + "docstring": null + }, + "key": { + "name": "key", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.key", + "signature": "", + "docstring": null + }, + "serialize": { + "name": "serialize", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.serialize", + "signature": "", + "docstring": null + }, + "deserialize": { + "name": "deserialize", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.deserialize", + "signature": "", + "docstring": null + }, + "ttl_seconds": { + "name": "ttl_seconds", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.ttl_seconds", + "signature": "", + "docstring": null + }, + "load": { + "name": "load", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.load", + "signature": "", + "docstring": "Load credentials from Redis.\n\nIf no value exists for the configured key, or if the stored\npayload cannot be successfully deserialized, this method\nreturns ``None``.\n\nThe store does not attempt to validate the returned credentials\nor determine whether they are expired or otherwise usable.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to Redis.\n\nAny previously stored credentials under the same key are\noverwritten. If a TTL is configured, the credentials will\nexpire automatically after the specified duration.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.clear", + "signature": "", + "docstring": "Remove stored credentials from Redis.\n\nThis operation deletes the configured Redis key if it exists.\nImplementations should treat this method as idempotent." + } + } + }, + "pickle": { + "name": "pickle", + "kind": "module", + "path": "mail_intake.credentials.pickle", + "signature": null, + "docstring": "Local 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": { + "pickle": { + "name": "pickle", + "kind": "alias", + "path": "mail_intake.credentials.pickle.pickle", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.pickle.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.pickle.TypeVar", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.pickle.CredentialStore", + "signature": "", + "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.credentials.pickle.CredentialStore.load", + "signature": "", + "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.credentials.pickle.CredentialStore.save", + "signature": "", + "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.credentials.pickle.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThis implementation:\n- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n\nCredential lifecycle management, validation, and refresh logic are\nexplicitly 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": "", + "docstring": "Load credentials from the local filesystem.\n\nIf the credential file does not exist or cannot be successfully\ndeserialized, this method returns ``None``.\n\nThe store does not attempt to validate or interpret the returned\ncredentials.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to the local filesystem.\n\nAny previously stored credentials at the configured path are\noverwritten.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", + "signature": "", + "docstring": "Remove persisted credentials from the local filesystem.\n\nThis method deletes the credential file if it exists and should\nbe treated as an idempotent operation." + } + } + } + } + }, + "redis": { + "name": "redis", + "kind": "module", + "path": "mail_intake.credentials.redis", + "signature": null, + "docstring": "Redis-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- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", + "members": { + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.redis.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.redis.TypeVar", + "signature": "", + "docstring": null + }, + "Callable": { + "name": "Callable", + "kind": "alias", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.redis.CredentialStore", + "signature": "", + "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.credentials.redis.CredentialStore.load", + "signature": "", + "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.credentials.redis.CredentialStore.save", + "signature": "", + "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.credentials.redis.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThe store is intentionally generic and delegates all serialization\nconcerns to caller-provided functions. This avoids unsafe mechanisms\nsuch as pickle and allows credential formats to be explicitly\ncontrolled and audited.\n\nThis class is responsible only for persistence and retrieval.\nIt does not interpret, validate, refresh, or otherwise manage\nthe lifecycle of the credentials being stored.", + "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": "", + "docstring": "Load credentials from Redis.\n\nIf no value exists for the configured key, or if the stored\npayload cannot be successfully deserialized, this method\nreturns ``None``.\n\nThe store does not attempt to validate the returned credentials\nor determine whether they are expired or otherwise usable.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to Redis.\n\nAny previously stored credentials under the same key are\noverwritten. If a TTL is configured, the credentials will\nexpire automatically after the specified duration.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", + "signature": "", + "docstring": "Remove stored credentials from Redis.\n\nThis operation deletes the configured Redis key if it exists.\nImplementations should treat this method as idempotent." + } + } + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + } + } + }, + "store": { + "name": "store", + "kind": "module", + "path": "mail_intake.credentials.store", + "signature": null, + "docstring": "Credential 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": { + "ABC": { + "name": "ABC", + "kind": "alias", + "path": "mail_intake.credentials.store.ABC", + "signature": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.credentials.store.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.credentials.store.Generic", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.store.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.store.TypeVar", + "signature": "", + "docstring": null + }, + "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": "", + "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.credentials.store.CredentialStore.load", + "signature": "", + "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.credentials.store.CredentialStore.save", + "signature": "", + "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.credentials.store.CredentialStore.clear", + "signature": "", + "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." + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.credentials.pickle.json b/mcp_docs/modules/mail_intake.credentials.pickle.json new file mode 100644 index 0000000..20aa133 --- /dev/null +++ b/mcp_docs/modules/mail_intake.credentials.pickle.json @@ -0,0 +1,104 @@ +{ + "module": "mail_intake.credentials.pickle", + "content": { + "path": "mail_intake.credentials.pickle", + "docstring": "Local 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": { + "pickle": { + "name": "pickle", + "kind": "alias", + "path": "mail_intake.credentials.pickle.pickle", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.pickle.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.pickle.TypeVar", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.pickle.CredentialStore", + "signature": "", + "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.credentials.pickle.CredentialStore.load", + "signature": "", + "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.credentials.pickle.CredentialStore.save", + "signature": "", + "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.credentials.pickle.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThis implementation:\n- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n\nCredential lifecycle management, validation, and refresh logic are\nexplicitly 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": "", + "docstring": "Load credentials from the local filesystem.\n\nIf the credential file does not exist or cannot be successfully\ndeserialized, this method returns ``None``.\n\nThe store does not attempt to validate or interpret the returned\ncredentials.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to the local filesystem.\n\nAny previously stored credentials at the configured path are\noverwritten.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", + "signature": "", + "docstring": "Remove persisted credentials from the local filesystem.\n\nThis method deletes the credential file if it exists and should\nbe treated as an idempotent operation." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.credentials.redis.json b/mcp_docs/modules/mail_intake.credentials.redis.json new file mode 100644 index 0000000..df944a2 --- /dev/null +++ b/mcp_docs/modules/mail_intake.credentials.redis.json @@ -0,0 +1,139 @@ +{ + "module": "mail_intake.credentials.redis", + "content": { + "path": "mail_intake.credentials.redis", + "docstring": "Redis-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- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", + "objects": { + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.redis.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.redis.TypeVar", + "signature": "", + "docstring": null + }, + "Callable": { + "name": "Callable", + "kind": "alias", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.redis.CredentialStore", + "signature": "", + "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.credentials.redis.CredentialStore.load", + "signature": "", + "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.credentials.redis.CredentialStore.save", + "signature": "", + "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.credentials.redis.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThe store is intentionally generic and delegates all serialization\nconcerns to caller-provided functions. This avoids unsafe mechanisms\nsuch as pickle and allows credential formats to be explicitly\ncontrolled and audited.\n\nThis class is responsible only for persistence and retrieval.\nIt does not interpret, validate, refresh, or otherwise manage\nthe lifecycle of the credentials being stored.", + "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": "", + "docstring": "Load credentials from Redis.\n\nIf no value exists for the configured key, or if the stored\npayload cannot be successfully deserialized, this method\nreturns ``None``.\n\nThe store does not attempt to validate the returned credentials\nor determine whether they are expired or otherwise usable.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to Redis.\n\nAny previously stored credentials under the same key are\noverwritten. If a TTL is configured, the credentials will\nexpire automatically after the specified duration.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", + "signature": "", + "docstring": "Remove stored credentials from Redis.\n\nThis operation deletes the configured Redis key if it exists.\nImplementations should treat this method as idempotent." + } + } + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.credentials.store.json b/mcp_docs/modules/mail_intake.credentials.store.json new file mode 100644 index 0000000..264106b --- /dev/null +++ b/mcp_docs/modules/mail_intake.credentials.store.json @@ -0,0 +1,81 @@ +{ + "module": "mail_intake.credentials.store", + "content": { + "path": "mail_intake.credentials.store", + "docstring": "Credential 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": { + "ABC": { + "name": "ABC", + "kind": "alias", + "path": "mail_intake.credentials.store.ABC", + "signature": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.credentials.store.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.credentials.store.Generic", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.store.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.store.TypeVar", + "signature": "", + "docstring": null + }, + "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": "", + "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.credentials.store.CredentialStore.load", + "signature": "", + "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.credentials.store.CredentialStore.save", + "signature": "", + "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.credentials.store.CredentialStore.clear", + "signature": "", + "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." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.exceptions.json b/mcp_docs/modules/mail_intake.exceptions.json new file mode 100644 index 0000000..858b03f --- /dev/null +++ b/mcp_docs/modules/mail_intake.exceptions.json @@ -0,0 +1,37 @@ +{ + "module": "mail_intake.exceptions", + "content": { + "path": "mail_intake.exceptions", + "docstring": "Exception 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": "", + "docstring": "Base exception for all Mail Intake errors.\n\nThis is the root of the Mail Intake exception hierarchy.\nAll errors raised by the library must derive from this class.\n\nConsumers should generally catch this type when handling\nlibrary-level failures." + }, + "MailIntakeAuthError": { + "name": "MailIntakeAuthError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeAuthError", + "signature": "", + "docstring": "Authentication and credential-related failures.\n\nRaised when authentication providers are unable to acquire,\nrefresh, or persist valid credentials." + }, + "MailIntakeAdapterError": { + "name": "MailIntakeAdapterError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeAdapterError", + "signature": "", + "docstring": "Errors raised by mail provider adapters.\n\nRaised when a provider adapter encounters API errors,\ntransport failures, or invalid provider responses." + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.ingestion.json b/mcp_docs/modules/mail_intake.ingestion.json new file mode 100644 index 0000000..0aede2c --- /dev/null +++ b/mcp_docs/modules/mail_intake.ingestion.json @@ -0,0 +1,280 @@ +{ + "module": "mail_intake.ingestion", + "content": { + "path": "mail_intake.ingestion", + "docstring": "Mail 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- 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.", + "objects": { + "MailIntakeReader": { + "name": "MailIntakeReader", + "kind": "class", + "path": "mail_intake.ingestion.MailIntakeReader", + "signature": "", + "docstring": "High-level read-only ingestion interface.\n\nThis class is the **primary entry point** for consumers of the Mail\nIntake library.\n\nIt 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\nThis class is intentionally:\n- Provider-agnostic\n- Stateless beyond iteration scope\n- Read-only", + "members": { + "iter_messages": { + "name": "iter_messages", + "kind": "function", + "path": "mail_intake.ingestion.MailIntakeReader.iter_messages", + "signature": "", + "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nYields:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + }, + "iter_threads": { + "name": "iter_threads", + "kind": "function", + "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", + "signature": "", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nMessages are grouped by `thread_id` and yielded as complete thread\nobjects containing all associated messages.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nReturns:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + } + } + }, + "reader": { + "name": "reader", + "kind": "module", + "path": "mail_intake.ingestion.reader", + "signature": null, + "docstring": "High-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- 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": { + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.ingestion.reader.datetime", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeAdapter", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.iter_message_refs", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_message", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_thread", + "signature": "", + "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." + } + } + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", + "signature": "", + "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": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", + "signature": "", + "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": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis 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": "", + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", + "signature": "", + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", + "signature": "", + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", + "signature": "", + "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": "", + "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": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"john@example.com\", \"John Doe\")``\n ``\"john@example.com\"`` → ``(\"john@example.com\", None)``" + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.ingestion.reader.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "MailIntakeReader": { + "name": "MailIntakeReader", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeReader", + "signature": "", + "docstring": "High-level read-only ingestion interface.\n\nThis class is the **primary entry point** for consumers of the Mail\nIntake library.\n\nIt 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\nThis class is intentionally:\n- Provider-agnostic\n- Stateless beyond iteration scope\n- Read-only", + "members": { + "iter_messages": { + "name": "iter_messages", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", + "signature": "", + "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nYields:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + }, + "iter_threads": { + "name": "iter_threads", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", + "signature": "", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nMessages are grouped by `thread_id` and yielded as complete thread\nobjects containing all associated messages.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nReturns:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.ingestion.reader.json b/mcp_docs/modules/mail_intake.ingestion.reader.json new file mode 100644 index 0000000..a6fcc96 --- /dev/null +++ b/mcp_docs/modules/mail_intake.ingestion.reader.json @@ -0,0 +1,248 @@ +{ + "module": "mail_intake.ingestion.reader", + "content": { + "path": "mail_intake.ingestion.reader", + "docstring": "High-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- 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": { + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.ingestion.reader.datetime", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeAdapter", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.iter_message_refs", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_message", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_thread", + "signature": "", + "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." + } + } + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", + "signature": "", + "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": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", + "signature": "", + "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": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis 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": "", + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", + "signature": "", + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", + "signature": "", + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", + "signature": "", + "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": "", + "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": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"john@example.com\", \"John Doe\")``\n ``\"john@example.com\"`` → ``(\"john@example.com\", None)``" + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.ingestion.reader.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "MailIntakeReader": { + "name": "MailIntakeReader", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeReader", + "signature": "", + "docstring": "High-level read-only ingestion interface.\n\nThis class is the **primary entry point** for consumers of the Mail\nIntake library.\n\nIt 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\nThis class is intentionally:\n- Provider-agnostic\n- Stateless beyond iteration scope\n- Read-only", + "members": { + "iter_messages": { + "name": "iter_messages", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", + "signature": "", + "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nYields:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + }, + "iter_threads": { + "name": "iter_threads", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", + "signature": "", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nMessages are grouped by `thread_id` and yielded as complete thread\nobjects containing all associated messages.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nReturns:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.json b/mcp_docs/modules/mail_intake.json new file mode 100644 index 0000000..738c689 --- /dev/null +++ b/mcp_docs/modules/mail_intake.json @@ -0,0 +1,1996 @@ +{ + "module": "mail_intake", + "content": { + "path": "mail_intake", + "docstring": "Mail Intake — provider-agnostic, read-only email ingestion framework.\n\nMail Intake is a **contract-first library** designed to ingest, parse, and\nnormalize email data from external providers (such as Gmail) into clean,\nprovider-agnostic domain models.\n\nThe library is intentionally structured around clear layers, each exposed\nas a first-class module at the package root:\n\n- adapters: provider-specific access (e.g. Gmail)\n- auth: authentication providers and credential lifecycle management\n- credentials: credential persistence abstractions and implementations\n- parsers: extraction and normalization of message content\n- ingestion: orchestration and high-level ingestion workflows\n- models: canonical, provider-agnostic data representations\n- config: explicit global configuration\n- exceptions: library-defined error hierarchy\n\nThe package root acts as a **namespace**, not a facade. Consumers are\nexpected to import functionality explicitly from the appropriate module.\n\n----------------------------------------------------------------------\nInstallation\n----------------------------------------------------------------------\n\nInstall using pip:\n\n pip install mail-intake\n\nOr with Poetry:\n\n poetry add mail-intake\n\nMail Intake is pure Python and has no runtime dependencies beyond those\nrequired by the selected provider (for example, Google APIs for Gmail).\n\n----------------------------------------------------------------------\nBasic Usage\n----------------------------------------------------------------------\n\nMinimal Gmail ingestion example (local development):\n\n from mail_intake.ingestion import MailIntakeReader\n from mail_intake.adapters import MailIntakeGmailAdapter\n from mail_intake.auth import MailIntakeGoogleAuth\n from mail_intake.credentials import PickleCredentialStore\n\n store = PickleCredentialStore(path=\"token.pickle\")\n\n auth = MailIntakeGoogleAuth(\n credentials_path=\"credentials.json\",\n store=store,\n scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n )\n\n adapter = MailIntakeGmailAdapter(auth_provider=auth)\n reader = MailIntakeReader(adapter)\n\n for message in reader.iter_messages(\"from:recruiter@example.com\"):\n print(message.subject, message.from_email)\n\nIterating over threads:\n\n for thread in reader.iter_threads(\"subject:Interview\"):\n print(thread.normalized_subject, len(thread.messages))\n\n----------------------------------------------------------------------\nExtensibility Model\n----------------------------------------------------------------------\n\nMail Intake is designed to be extensible via **public contracts** exposed\nthrough its modules:\n\n- Users MAY implement their own mail adapters by subclassing\n ``adapters.MailIntakeAdapter``\n- Users MAY implement their own authentication providers by subclassing\n ``auth.MailIntakeAuthProvider[T]``\n- Users MAY implement their own credential persistence layers by\n implementing ``credentials.CredentialStore[T]``\n\nUsers SHOULD NOT subclass built-in adapter implementations. Built-in\nadapters (such as Gmail) are reference implementations and may change\ninternally without notice.\n\n----------------------------------------------------------------------\nPublic API Surface\n----------------------------------------------------------------------\n\nThe supported public API consists of the following top-level modules:\n\n- mail_intake.ingestion\n- mail_intake.adapters\n- mail_intake.auth\n- mail_intake.credentials\n- mail_intake.parsers\n- mail_intake.models\n- mail_intake.config\n- mail_intake.exceptions\n\nClasses and functions should be imported explicitly from these modules.\nNo individual symbols are re-exported at the package root.\n\n----------------------------------------------------------------------\nDesign Guarantees\n----------------------------------------------------------------------\n\n- Read-only access: no mutation of provider state\n- Provider-agnostic domain models\n- Explicit configuration and dependency injection\n- No implicit global state or environment reads\n- Deterministic, testable behavior\n- Distributed-safe authentication design\n\nMail Intake favors correctness, clarity, and explicitness over convenience\nshortcuts.\n\n## Core Philosophy\n\n`Mail Intake` is built as a **contract-first ingestion pipeline**:\n\n1. **Layered Decoupling**: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.\n2. **Provider Agnosticism**: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.\n3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring side-effect-free ingestion.\n\n## Documentation Design\n\nFollow these \"AI-Native\" docstring principles across the codebase:\n\n### For Humans\n- **Namespace Clarity**: Always specify which module a class or function belongs to.\n- **Contract Explanations**: Use the `adapters` and `auth` base classes to explain extension requirements.\n\n### For LLMs\n- **Dotted Paths**: Use full dotted paths in docstrings to help agents link concepts across modules.\n- **Typed Interfaces**: Provide `.pyi` stubs for every public module to ensure perfect context for AI coding tools.\n- **Canonical Exceptions**: Always use `: description` pairs in `Raises` blocks to enable structured error analysis.", + "objects": { + "config": { + "name": "config", + "kind": "module", + "path": "mail_intake.config", + "signature": null, + "docstring": "Global configuration models for Mail Intake.\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.", + "members": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.config.dataclass", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.config.Optional", + "signature": "", + "docstring": null + }, + "MailIntakeConfig": { + "name": "MailIntakeConfig", + "kind": "class", + "path": "mail_intake.config.MailIntakeConfig", + "signature": "", + "docstring": "Global configuration for mail-intake.\n\nThis configuration is intentionally explicit and immutable.\nNo implicit environment reads or global state.\n\nDesign principles:\n- Immutable once constructed\n- Explicit configuration over implicit defaults\n- No direct environment or filesystem access\n\nThis model is safe to pass across layers and suitable for serialization.", + "members": { + "provider": { + "name": "provider", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.provider", + "signature": null, + "docstring": "Identifier of the mail provider to use (e.g., ``\"gmail\"``)." + }, + "user_id": { + "name": "user_id", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.user_id", + "signature": null, + "docstring": "Provider-specific user identifier. Defaults to the authenticated user." + }, + "readonly": { + "name": "readonly", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.readonly", + "signature": null, + "docstring": "Whether ingestion should operate in read-only mode." + }, + "credentials_path": { + "name": "credentials_path", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.credentials_path", + "signature": null, + "docstring": "Optional path to provider credentials configuration." + }, + "token_path": { + "name": "token_path", + "kind": "attribute", + "path": "mail_intake.config.MailIntakeConfig.token_path", + "signature": null, + "docstring": "Optional path to persisted authentication tokens." + } + } + } + } + }, + "exceptions": { + "name": "exceptions", + "kind": "module", + "path": "mail_intake.exceptions", + "signature": null, + "docstring": "Exception hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", + "members": { + "MailIntakeError": { + "name": "MailIntakeError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeError", + "signature": "", + "docstring": "Base exception for all Mail Intake errors.\n\nThis is the root of the Mail Intake exception hierarchy.\nAll errors raised by the library must derive from this class.\n\nConsumers should generally catch this type when handling\nlibrary-level failures." + }, + "MailIntakeAuthError": { + "name": "MailIntakeAuthError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeAuthError", + "signature": "", + "docstring": "Authentication and credential-related failures.\n\nRaised when authentication providers are unable to acquire,\nrefresh, or persist valid credentials." + }, + "MailIntakeAdapterError": { + "name": "MailIntakeAdapterError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeAdapterError", + "signature": "", + "docstring": "Errors raised by mail provider adapters.\n\nRaised when a provider adapter encounters API errors,\ntransport failures, or invalid provider responses." + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.exceptions.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + } + } + }, + "adapters": { + "name": "adapters", + "kind": "module", + "path": "mail_intake.adapters", + "signature": null, + "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.", + "members": { + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.adapters.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.adapters.base.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.base.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.base.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.base.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.adapters.gmail.Any", + "signature": "", + "docstring": null + }, + "build": { + "name": "build", + "kind": "alias", + "path": "mail_intake.adapters.gmail.build", + "signature": "", + "docstring": null + }, + "HttpError": { + "name": "HttpError", + "kind": "alias", + "path": "mail_intake.adapters.gmail.HttpError", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAdapter", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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." + } + } + } + } + } + } + }, + "auth": { + "name": "auth", + "kind": "module", + "path": "mail_intake.auth", + "signature": null, + "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.", + "members": { + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.auth.MailIntakeAuthProvider", + "signature": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "store": { + "name": "store", + "kind": "attribute", + "path": "mail_intake.auth.MailIntakeGoogleAuth.store", + "signature": "", + "docstring": null + }, + "scopes": { + "name": "scopes", + "kind": "attribute", + "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes", + "signature": "", + "docstring": null + }, + "get_credentials": { + "name": "get_credentials", + "kind": "function", + "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials", + "signature": "", + "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": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.auth.base.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.auth.base.Generic", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.auth.base.TypeVar", + "signature": "", + "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": "", + "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": "", + "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": "", + "docstring": null + }, + "Sequence": { + "name": "Sequence", + "kind": "alias", + "path": "mail_intake.auth.google.Sequence", + "signature": "", + "docstring": null + }, + "google": { + "name": "google", + "kind": "alias", + "path": "mail_intake.auth.google.google", + "signature": "", + "docstring": null + }, + "Request": { + "name": "Request", + "kind": "alias", + "path": "mail_intake.auth.google.Request", + "signature": "", + "docstring": null + }, + "InstalledAppFlow": { + "name": "InstalledAppFlow", + "kind": "alias", + "path": "mail_intake.auth.google.InstalledAppFlow", + "signature": "", + "docstring": null + }, + "Credentials": { + "name": "Credentials", + "kind": "alias", + "path": "mail_intake.auth.google.Credentials", + "signature": "", + "docstring": null + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.auth.google.MailIntakeAuthProvider", + "signature": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "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": "", + "docstring": null + } + } + } + } + }, + "credentials": { + "name": "credentials", + "kind": "module", + "path": "mail_intake.credentials", + "signature": null, + "docstring": "Credential 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- 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.", + "members": { + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.CredentialStore", + "signature": "", + "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.credentials.CredentialStore.load", + "signature": "", + "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.credentials.CredentialStore.save", + "signature": "", + "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.credentials.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "PickleCredentialStore": { + "name": "PickleCredentialStore", + "kind": "class", + "path": "mail_intake.credentials.PickleCredentialStore", + "signature": "", + "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\nThis implementation:\n- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n\nCredential lifecycle management, validation, and refresh logic are\nexplicitly out of scope for this class.", + "members": { + "path": { + "name": "path", + "kind": "attribute", + "path": "mail_intake.credentials.PickleCredentialStore.path", + "signature": "", + "docstring": null + }, + "load": { + "name": "load", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.load", + "signature": "", + "docstring": "Load credentials from the local filesystem.\n\nIf the credential file does not exist or cannot be successfully\ndeserialized, this method returns ``None``.\n\nThe store does not attempt to validate or interpret the returned\ncredentials.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to the local filesystem.\n\nAny previously stored credentials at the configured path are\noverwritten.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.PickleCredentialStore.clear", + "signature": "", + "docstring": "Remove persisted credentials from the local filesystem.\n\nThis method deletes the credential file if it exists and should\nbe treated as an idempotent operation." + } + } + }, + "RedisCredentialStore": { + "name": "RedisCredentialStore", + "kind": "class", + "path": "mail_intake.credentials.RedisCredentialStore", + "signature": "", + "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nThe store is intentionally generic and delegates all serialization\nconcerns to caller-provided functions. This avoids unsafe mechanisms\nsuch as pickle and allows credential formats to be explicitly\ncontrolled and audited.\n\nThis class is responsible only for persistence and retrieval.\nIt does not interpret, validate, refresh, or otherwise manage\nthe lifecycle of the credentials being stored.", + "members": { + "redis": { + "name": "redis", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.redis", + "signature": "", + "docstring": null + }, + "key": { + "name": "key", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.key", + "signature": "", + "docstring": null + }, + "serialize": { + "name": "serialize", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.serialize", + "signature": "", + "docstring": null + }, + "deserialize": { + "name": "deserialize", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.deserialize", + "signature": "", + "docstring": null + }, + "ttl_seconds": { + "name": "ttl_seconds", + "kind": "attribute", + "path": "mail_intake.credentials.RedisCredentialStore.ttl_seconds", + "signature": "", + "docstring": null + }, + "load": { + "name": "load", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.load", + "signature": "", + "docstring": "Load credentials from Redis.\n\nIf no value exists for the configured key, or if the stored\npayload cannot be successfully deserialized, this method\nreturns ``None``.\n\nThe store does not attempt to validate the returned credentials\nor determine whether they are expired or otherwise usable.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to Redis.\n\nAny previously stored credentials under the same key are\noverwritten. If a TTL is configured, the credentials will\nexpire automatically after the specified duration.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.RedisCredentialStore.clear", + "signature": "", + "docstring": "Remove stored credentials from Redis.\n\nThis operation deletes the configured Redis key if it exists.\nImplementations should treat this method as idempotent." + } + } + }, + "pickle": { + "name": "pickle", + "kind": "module", + "path": "mail_intake.credentials.pickle", + "signature": null, + "docstring": "Local 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": { + "pickle": { + "name": "pickle", + "kind": "alias", + "path": "mail_intake.credentials.pickle.pickle", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.pickle.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.pickle.TypeVar", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.pickle.CredentialStore", + "signature": "", + "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.credentials.pickle.CredentialStore.load", + "signature": "", + "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.credentials.pickle.CredentialStore.save", + "signature": "", + "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.credentials.pickle.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThis implementation:\n- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n\nCredential lifecycle management, validation, and refresh logic are\nexplicitly 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": "", + "docstring": "Load credentials from the local filesystem.\n\nIf the credential file does not exist or cannot be successfully\ndeserialized, this method returns ``None``.\n\nThe store does not attempt to validate or interpret the returned\ncredentials.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to the local filesystem.\n\nAny previously stored credentials at the configured path are\noverwritten.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", + "signature": "", + "docstring": "Remove persisted credentials from the local filesystem.\n\nThis method deletes the credential file if it exists and should\nbe treated as an idempotent operation." + } + } + } + } + }, + "redis": { + "name": "redis", + "kind": "module", + "path": "mail_intake.credentials.redis", + "signature": null, + "docstring": "Redis-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- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", + "members": { + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.redis.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.redis.TypeVar", + "signature": "", + "docstring": null + }, + "Callable": { + "name": "Callable", + "kind": "alias", + "path": "mail_intake.credentials.redis.Callable", + "signature": "", + "docstring": null + }, + "CredentialStore": { + "name": "CredentialStore", + "kind": "class", + "path": "mail_intake.credentials.redis.CredentialStore", + "signature": "", + "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.credentials.redis.CredentialStore.load", + "signature": "", + "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.credentials.redis.CredentialStore.save", + "signature": "", + "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.credentials.redis.CredentialStore.clear", + "signature": "", + "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." + } + } + }, + "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": "", + "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\nThe store is intentionally generic and delegates all serialization\nconcerns to caller-provided functions. This avoids unsafe mechanisms\nsuch as pickle and allows credential formats to be explicitly\ncontrolled and audited.\n\nThis class is responsible only for persistence and retrieval.\nIt does not interpret, validate, refresh, or otherwise manage\nthe lifecycle of the credentials being stored.", + "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": "", + "docstring": "Load credentials from Redis.\n\nIf no value exists for the configured key, or if the stored\npayload cannot be successfully deserialized, this method\nreturns ``None``.\n\nThe store does not attempt to validate the returned credentials\nor determine whether they are expired or otherwise usable.\n\nReturns:\n An instance of type ``T`` if credentials are present and\n successfully deserialized; otherwise ``None``." + }, + "save": { + "name": "save", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.save", + "signature": "", + "docstring": "Persist credentials to Redis.\n\nAny previously stored credentials under the same key are\noverwritten. If a TTL is configured, the credentials will\nexpire automatically after the specified duration.\n\nArgs:\n credentials:\n The credential object to persist." + }, + "clear": { + "name": "clear", + "kind": "function", + "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", + "signature": "", + "docstring": "Remove stored credentials from Redis.\n\nThis operation deletes the configured Redis key if it exists.\nImplementations should treat this method as idempotent." + } + } + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + } + } + }, + "store": { + "name": "store", + "kind": "module", + "path": "mail_intake.credentials.store", + "signature": null, + "docstring": "Credential 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": { + "ABC": { + "name": "ABC", + "kind": "alias", + "path": "mail_intake.credentials.store.ABC", + "signature": "", + "docstring": null + }, + "abstractmethod": { + "name": "abstractmethod", + "kind": "alias", + "path": "mail_intake.credentials.store.abstractmethod", + "signature": "", + "docstring": null + }, + "Generic": { + "name": "Generic", + "kind": "alias", + "path": "mail_intake.credentials.store.Generic", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.credentials.store.Optional", + "signature": "", + "docstring": null + }, + "TypeVar": { + "name": "TypeVar", + "kind": "alias", + "path": "mail_intake.credentials.store.TypeVar", + "signature": "", + "docstring": null + }, + "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": "", + "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.credentials.store.CredentialStore.load", + "signature": "", + "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.credentials.store.CredentialStore.save", + "signature": "", + "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.credentials.store.CredentialStore.clear", + "signature": "", + "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." + } + } + } + } + } + } + }, + "ingestion": { + "name": "ingestion", + "kind": "module", + "path": "mail_intake.ingestion", + "signature": null, + "docstring": "Mail 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- 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.", + "members": { + "MailIntakeReader": { + "name": "MailIntakeReader", + "kind": "class", + "path": "mail_intake.ingestion.MailIntakeReader", + "signature": "", + "docstring": "High-level read-only ingestion interface.\n\nThis class is the **primary entry point** for consumers of the Mail\nIntake library.\n\nIt 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\nThis class is intentionally:\n- Provider-agnostic\n- Stateless beyond iteration scope\n- Read-only", + "members": { + "iter_messages": { + "name": "iter_messages", + "kind": "function", + "path": "mail_intake.ingestion.MailIntakeReader.iter_messages", + "signature": "", + "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nYields:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + }, + "iter_threads": { + "name": "iter_threads", + "kind": "function", + "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", + "signature": "", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nMessages are grouped by `thread_id` and yielded as complete thread\nobjects containing all associated messages.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nReturns:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + } + } + }, + "reader": { + "name": "reader", + "kind": "module", + "path": "mail_intake.ingestion.reader", + "signature": null, + "docstring": "High-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- 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": { + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.ingestion.reader.datetime", + "signature": "", + "docstring": null + }, + "Iterator": { + "name": "Iterator", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Iterator", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.ingestion.reader.Any", + "signature": "", + "docstring": null + }, + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeAdapter", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.iter_message_refs", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_message", + "signature": "", + "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.ingestion.reader.MailIntakeAdapter.fetch_thread", + "signature": "", + "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." + } + } + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", + "signature": "", + "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": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", + "signature": "", + "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": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis 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": "", + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", + "signature": "", + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", + "signature": "", + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", + "signature": "", + "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": "", + "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": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"john@example.com\", \"John Doe\")``\n ``\"john@example.com\"`` → ``(\"john@example.com\", None)``" + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.ingestion.reader.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "MailIntakeReader": { + "name": "MailIntakeReader", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeReader", + "signature": "", + "docstring": "High-level read-only ingestion interface.\n\nThis class is the **primary entry point** for consumers of the Mail\nIntake library.\n\nIt 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\nThis class is intentionally:\n- Provider-agnostic\n- Stateless beyond iteration scope\n- Read-only", + "members": { + "iter_messages": { + "name": "iter_messages", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", + "signature": "", + "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nYields:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + }, + "iter_threads": { + "name": "iter_threads", + "kind": "function", + "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", + "signature": "", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nMessages are grouped by `thread_id` and yielded as complete thread\nobjects containing all associated messages.\n\nArgs:\n query: Provider-specific query string used to filter messages.\n\nReturns:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n MailIntakeParsingError: If a message cannot be parsed." + } + } + } + } + } + } + }, + "models": { + "name": "models", + "kind": "module", + "path": "mail_intake.models", + "signature": null, + "docstring": "Domain models for Mail Intake.\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n- Represent fully parsed and normalized mail data\n- Are safe to persist, serialize, and index\n- Contain no provider-specific payloads or API semantics\n- Serve as stable inputs for downstream processing and analysis\n\nThese models form the core internal data contract of the library.", + "members": { + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.timestamp", + "signature": "", + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.from_email", + "signature": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.snippet", + "signature": "", + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.raw_headers", + "signature": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.models.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.", + "members": { + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.normalized_subject", + "signature": "", + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.participants", + "signature": "", + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.messages", + "signature": "", + "docstring": "Ordered list of messages belonging to this thread." + }, + "last_activity_at": { + "name": "last_activity_at", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.last_activity_at", + "signature": "", + "docstring": "Timestamp of the most recent message in the thread." + }, + "add_message": { + "name": "add_message", + "kind": "function", + "path": "mail_intake.models.MailIntakeThread.add_message", + "signature": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "message": { + "name": "message", + "kind": "module", + "path": "mail_intake.models.message", + "signature": null, + "docstring": "Message domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.", + "members": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.message.dataclass", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.message.datetime", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.message.Optional", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.models.message.Dict", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.message.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.message_id", + "signature": null, + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.timestamp", + "signature": null, + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_email", + "signature": null, + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_name", + "signature": null, + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.subject", + "signature": null, + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.body_text", + "signature": null, + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.snippet", + "signature": null, + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.raw_headers", + "signature": null, + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + } + } + }, + "thread": { + "name": "thread", + "kind": "module", + "path": "mail_intake.models.thread", + "signature": null, + "docstring": "Thread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.", + "members": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.thread.dataclass", + "signature": "", + "docstring": null + }, + "field": { + "name": "field", + "kind": "alias", + "path": "mail_intake.models.thread.field", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.thread.datetime", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.models.thread.List", + "signature": "", + "docstring": null + }, + "Set": { + "name": "Set", + "kind": "alias", + "path": "mail_intake.models.thread.Set", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", + "signature": "", + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_email", + "signature": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.snippet", + "signature": "", + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.raw_headers", + "signature": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.", + "members": { + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.normalized_subject", + "signature": null, + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.participants", + "signature": null, + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.models.thread.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.models.thread.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.models.thread.MailIntakeThread.add_message", + "signature": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.thread.Optional", + "signature": "", + "docstring": null + } + } + } + } + }, + "parsers": { + "name": "parsers", + "kind": "module", + "path": "mail_intake.parsers", + "signature": null, + "docstring": "Message 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- 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- 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.", + "members": { + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"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": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + }, + "body": { + "name": "body", + "kind": "module", + "path": "mail_intake.parsers.body", + "signature": null, + "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", + "members": { + "base64": { + "name": "base64", + "kind": "alias", + "path": "mail_intake.parsers.body.base64", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.body.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.parsers.body.Any", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.body.Optional", + "signature": "", + "docstring": null + }, + "BeautifulSoup": { + "name": "BeautifulSoup", + "kind": "alias", + "path": "mail_intake.parsers.body.BeautifulSoup", + "signature": "", + "docstring": null + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.parsers.body.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.body.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + } + } + }, + "headers": { + "name": "headers", + "kind": "module", + "path": "mail_intake.parsers.headers", + "signature": null, + "docstring": "Message header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", + "members": { + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.headers.Dict", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.parsers.headers.List", + "signature": "", + "docstring": null + }, + "Tuple": { + "name": "Tuple", + "kind": "alias", + "path": "mail_intake.parsers.headers.Tuple", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.headers.Optional", + "signature": "", + "docstring": null + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.headers.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.headers.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"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": "Subject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.", + "members": { + "re": { + "name": "re", + "kind": "alias", + "path": "mail_intake.parsers.subject.re", + "signature": "", + "docstring": null + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.parsers.subject.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.models.json b/mcp_docs/modules/mail_intake.models.json new file mode 100644 index 0000000..eaa1357 --- /dev/null +++ b/mcp_docs/modules/mail_intake.models.json @@ -0,0 +1,415 @@ +{ + "module": "mail_intake.models", + "content": { + "path": "mail_intake.models", + "docstring": "Domain models for Mail Intake.\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n- Represent fully parsed and normalized mail data\n- Are safe to persist, serialize, and index\n- Contain no provider-specific payloads or API semantics\n- Serve as stable inputs for downstream processing and analysis\n\nThese models form the core internal data contract of the library.", + "objects": { + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.timestamp", + "signature": "", + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.from_email", + "signature": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.snippet", + "signature": "", + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeMessage.raw_headers", + "signature": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.models.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.", + "members": { + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.normalized_subject", + "signature": "", + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.participants", + "signature": "", + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.messages", + "signature": "", + "docstring": "Ordered list of messages belonging to this thread." + }, + "last_activity_at": { + "name": "last_activity_at", + "kind": "attribute", + "path": "mail_intake.models.MailIntakeThread.last_activity_at", + "signature": "", + "docstring": "Timestamp of the most recent message in the thread." + }, + "add_message": { + "name": "add_message", + "kind": "function", + "path": "mail_intake.models.MailIntakeThread.add_message", + "signature": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "message": { + "name": "message", + "kind": "module", + "path": "mail_intake.models.message", + "signature": null, + "docstring": "Message domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.", + "members": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.message.dataclass", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.message.datetime", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.message.Optional", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.models.message.Dict", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.message.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.message_id", + "signature": null, + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.timestamp", + "signature": null, + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_email", + "signature": null, + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_name", + "signature": null, + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.subject", + "signature": null, + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.body_text", + "signature": null, + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.snippet", + "signature": null, + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.raw_headers", + "signature": null, + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + } + } + }, + "thread": { + "name": "thread", + "kind": "module", + "path": "mail_intake.models.thread", + "signature": null, + "docstring": "Thread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.", + "members": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.thread.dataclass", + "signature": "", + "docstring": null + }, + "field": { + "name": "field", + "kind": "alias", + "path": "mail_intake.models.thread.field", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.thread.datetime", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.models.thread.List", + "signature": "", + "docstring": null + }, + "Set": { + "name": "Set", + "kind": "alias", + "path": "mail_intake.models.thread.Set", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", + "signature": "", + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_email", + "signature": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.snippet", + "signature": "", + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.raw_headers", + "signature": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.", + "members": { + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.normalized_subject", + "signature": null, + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.participants", + "signature": null, + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.models.thread.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.models.thread.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.models.thread.MailIntakeThread.add_message", + "signature": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.thread.Optional", + "signature": "", + "docstring": null + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.models.message.json b/mcp_docs/modules/mail_intake.models.message.json new file mode 100644 index 0000000..d1f0281 --- /dev/null +++ b/mcp_docs/modules/mail_intake.models.message.json @@ -0,0 +1,109 @@ +{ + "module": "mail_intake.models.message", + "content": { + "path": "mail_intake.models.message", + "docstring": "Message domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.", + "objects": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.message.dataclass", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.message.datetime", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.message.Optional", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.models.message.Dict", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.message.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.message_id", + "signature": null, + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.timestamp", + "signature": null, + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_email", + "signature": null, + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.from_name", + "signature": null, + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.subject", + "signature": null, + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.body_text", + "signature": null, + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.snippet", + "signature": null, + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.message.MailIntakeMessage.raw_headers", + "signature": null, + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.models.thread.json b/mcp_docs/modules/mail_intake.models.thread.json new file mode 100644 index 0000000..fd8b3ed --- /dev/null +++ b/mcp_docs/modules/mail_intake.models.thread.json @@ -0,0 +1,174 @@ +{ + "module": "mail_intake.models.thread", + "content": { + "path": "mail_intake.models.thread", + "docstring": "Thread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.", + "objects": { + "dataclass": { + "name": "dataclass", + "kind": "alias", + "path": "mail_intake.models.thread.dataclass", + "signature": "", + "docstring": null + }, + "field": { + "name": "field", + "kind": "alias", + "path": "mail_intake.models.thread.field", + "signature": "", + "docstring": null + }, + "datetime": { + "name": "datetime", + "kind": "alias", + "path": "mail_intake.models.thread.datetime", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.models.thread.List", + "signature": "", + "docstring": null + }, + "Set": { + "name": "Set", + "kind": "alias", + "path": "mail_intake.models.thread.Set", + "signature": "", + "docstring": null + }, + "MailIntakeMessage": { + "name": "MailIntakeMessage", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeMessage", + "signature": "", + "docstring": "Canonical internal representation of a single email message.\n\nThis model represents a fully parsed and normalized email message.\nIt is intentionally provider-agnostic and suitable for persistence,\nindexing, and downstream processing.\n\nNo provider-specific identifiers, payloads, or API semantics\nshould appear in this model.", + "members": { + "message_id": { + "name": "message_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.message_id", + "signature": "", + "docstring": "Provider-specific message identifier." + }, + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", + "signature": "", + "docstring": "Provider-specific thread identifier to which this message belongs." + }, + "timestamp": { + "name": "timestamp", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", + "signature": "", + "docstring": "Message timestamp as a timezone-naive UTC datetime." + }, + "from_email": { + "name": "from_email", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_email", + "signature": "", + "docstring": "Sender email address." + }, + "from_name": { + "name": "from_name", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.from_name", + "signature": "", + "docstring": "Optional human-readable sender name." + }, + "subject": { + "name": "subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.subject", + "signature": "", + "docstring": "Raw subject line of the message." + }, + "body_text": { + "name": "body_text", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.body_text", + "signature": "", + "docstring": "Extracted plain-text body content of the message." + }, + "snippet": { + "name": "snippet", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.snippet", + "signature": "", + "docstring": "Short provider-supplied preview snippet of the message." + }, + "raw_headers": { + "name": "raw_headers", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeMessage.raw_headers", + "signature": "", + "docstring": "Normalized mapping of message headers (header name → value)." + } + } + }, + "MailIntakeThread": { + "name": "MailIntakeThread", + "kind": "class", + "path": "mail_intake.models.thread.MailIntakeThread", + "signature": "", + "docstring": "Canonical internal representation of an email thread.\n\nA thread groups multiple related messages under a single subject\nand participant set. It is designed to support reasoning over\nconversational context such as job applications, interviews,\nfollow-ups, and ongoing discussions.\n\nThis model is provider-agnostic and safe to persist.", + "members": { + "thread_id": { + "name": "thread_id", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.thread_id", + "signature": null, + "docstring": "Provider-specific thread identifier." + }, + "normalized_subject": { + "name": "normalized_subject", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.normalized_subject", + "signature": null, + "docstring": "Normalized subject line used to group related messages." + }, + "participants": { + "name": "participants", + "kind": "attribute", + "path": "mail_intake.models.thread.MailIntakeThread.participants", + "signature": null, + "docstring": "Set of unique participant email addresses observed in the thread." + }, + "messages": { + "name": "messages", + "kind": "attribute", + "path": "mail_intake.models.thread.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.models.thread.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.models.thread.MailIntakeThread.add_message", + "signature": "", + "docstring": "Add a message to the thread and update derived fields.\n\nThis method:\n- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n\nArgs:\n message: Parsed mail message to add to the thread." + } + } + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.models.thread.Optional", + "signature": "", + "docstring": null + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.parsers.body.json b/mcp_docs/modules/mail_intake.parsers.body.json new file mode 100644 index 0000000..68b9dbc --- /dev/null +++ b/mcp_docs/modules/mail_intake.parsers.body.json @@ -0,0 +1,58 @@ +{ + "module": "mail_intake.parsers.body", + "content": { + "path": "mail_intake.parsers.body", + "docstring": "Message 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": { + "base64": { + "name": "base64", + "kind": "alias", + "path": "mail_intake.parsers.body.base64", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.body.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.parsers.body.Any", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.body.Optional", + "signature": "", + "docstring": null + }, + "BeautifulSoup": { + "name": "BeautifulSoup", + "kind": "alias", + "path": "mail_intake.parsers.body.BeautifulSoup", + "signature": "", + "docstring": null + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.parsers.body.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.body.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.parsers.headers.json b/mcp_docs/modules/mail_intake.parsers.headers.json new file mode 100644 index 0000000..11990c4 --- /dev/null +++ b/mcp_docs/modules/mail_intake.parsers.headers.json @@ -0,0 +1,51 @@ +{ + "module": "mail_intake.parsers.headers", + "content": { + "path": "mail_intake.parsers.headers", + "docstring": "Message header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", + "objects": { + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.headers.Dict", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.parsers.headers.List", + "signature": "", + "docstring": null + }, + "Tuple": { + "name": "Tuple", + "kind": "alias", + "path": "mail_intake.parsers.headers.Tuple", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.headers.Optional", + "signature": "", + "docstring": null + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.headers.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.headers.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"john@example.com\", \"John Doe\")``\n ``\"john@example.com\"`` → ``(\"john@example.com\", None)``" + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.parsers.json b/mcp_docs/modules/mail_intake.parsers.json new file mode 100644 index 0000000..4ec99d6 --- /dev/null +++ b/mcp_docs/modules/mail_intake.parsers.json @@ -0,0 +1,169 @@ +{ + "module": "mail_intake.parsers", + "content": { + "path": "mail_intake.parsers", + "docstring": "Message 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- 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- 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.", + "objects": { + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"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": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + }, + "body": { + "name": "body", + "kind": "module", + "path": "mail_intake.parsers.body", + "signature": null, + "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", + "members": { + "base64": { + "name": "base64", + "kind": "alias", + "path": "mail_intake.parsers.body.base64", + "signature": "", + "docstring": null + }, + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.body.Dict", + "signature": "", + "docstring": null + }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.parsers.body.Any", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.body.Optional", + "signature": "", + "docstring": null + }, + "BeautifulSoup": { + "name": "BeautifulSoup", + "kind": "alias", + "path": "mail_intake.parsers.body.BeautifulSoup", + "signature": "", + "docstring": null + }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.parsers.body.MailIntakeParsingError", + "signature": "", + "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models." + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.body.extract_body", + "signature": "", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n payload: Provider-native message payload dictionary.\n\nReturns:\n Extracted plain-text message body." + } + } + }, + "headers": { + "name": "headers", + "kind": "module", + "path": "mail_intake.parsers.headers", + "signature": null, + "docstring": "Message header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", + "members": { + "Dict": { + "name": "Dict", + "kind": "alias", + "path": "mail_intake.parsers.headers.Dict", + "signature": "", + "docstring": null + }, + "List": { + "name": "List", + "kind": "alias", + "path": "mail_intake.parsers.headers.List", + "signature": "", + "docstring": null + }, + "Tuple": { + "name": "Tuple", + "kind": "alias", + "path": "mail_intake.parsers.headers.Tuple", + "signature": "", + "docstring": null + }, + "Optional": { + "name": "Optional", + "kind": "alias", + "path": "mail_intake.parsers.headers.Optional", + "signature": "", + "docstring": null + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.headers.parse_headers", + "signature": "", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n raw_headers: List of header dictionaries, each containing\n ``name`` and ``value`` keys.\n\nReturns:\n Dictionary mapping lowercase header names to stripped values.\n\nExample:\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.headers.extract_sender", + "signature": "", + "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n headers: Normalized header dictionary as returned by\n :func:`parse_headers`.\n\nReturns:\n A tuple ``(email, name)`` where:\n - ``email`` is the sender email address\n - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n ``\"John Doe \"`` → ``(\"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": "Subject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.", + "members": { + "re": { + "name": "re", + "kind": "alias", + "path": "mail_intake.parsers.subject.re", + "signature": "", + "docstring": null + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.parsers.subject.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.parsers.subject.json b/mcp_docs/modules/mail_intake.parsers.subject.json new file mode 100644 index 0000000..8a9435b --- /dev/null +++ b/mcp_docs/modules/mail_intake.parsers.subject.json @@ -0,0 +1,23 @@ +{ + "module": "mail_intake.parsers.subject", + "content": { + "path": "mail_intake.parsers.subject", + "docstring": "Subject 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": { + "re": { + "name": "re", + "kind": "alias", + "path": "mail_intake.parsers.subject.re", + "signature": "", + "docstring": null + }, + "normalize_subject": { + "name": "normalize_subject", + "kind": "function", + "path": "mail_intake.parsers.subject.normalize_subject", + "signature": "", + "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\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\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n subject: Raw subject line from a message header.\n\nReturns:\n Normalized subject string suitable for thread grouping." + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/nav.json b/mcp_docs/nav.json new file mode 100644 index 0000000..10e1093 --- /dev/null +++ b/mcp_docs/nav.json @@ -0,0 +1,90 @@ +[ + { + "module": "mail_intake", + "resource": "doc://modules/mail_intake" + }, + { + "module": "mail_intake.adapters", + "resource": "doc://modules/mail_intake.adapters" + }, + { + "module": "mail_intake.adapters.base", + "resource": "doc://modules/mail_intake.adapters.base" + }, + { + "module": "mail_intake.adapters.gmail", + "resource": "doc://modules/mail_intake.adapters.gmail" + }, + { + "module": "mail_intake.auth", + "resource": "doc://modules/mail_intake.auth" + }, + { + "module": "mail_intake.auth.base", + "resource": "doc://modules/mail_intake.auth.base" + }, + { + "module": "mail_intake.auth.google", + "resource": "doc://modules/mail_intake.auth.google" + }, + { + "module": "mail_intake.config", + "resource": "doc://modules/mail_intake.config" + }, + { + "module": "mail_intake.credentials", + "resource": "doc://modules/mail_intake.credentials" + }, + { + "module": "mail_intake.credentials.pickle", + "resource": "doc://modules/mail_intake.credentials.pickle" + }, + { + "module": "mail_intake.credentials.redis", + "resource": "doc://modules/mail_intake.credentials.redis" + }, + { + "module": "mail_intake.credentials.store", + "resource": "doc://modules/mail_intake.credentials.store" + }, + { + "module": "mail_intake.exceptions", + "resource": "doc://modules/mail_intake.exceptions" + }, + { + "module": "mail_intake.ingestion", + "resource": "doc://modules/mail_intake.ingestion" + }, + { + "module": "mail_intake.ingestion.reader", + "resource": "doc://modules/mail_intake.ingestion.reader" + }, + { + "module": "mail_intake.models", + "resource": "doc://modules/mail_intake.models" + }, + { + "module": "mail_intake.models.message", + "resource": "doc://modules/mail_intake.models.message" + }, + { + "module": "mail_intake.models.thread", + "resource": "doc://modules/mail_intake.models.thread" + }, + { + "module": "mail_intake.parsers", + "resource": "doc://modules/mail_intake.parsers" + }, + { + "module": "mail_intake.parsers.body", + "resource": "doc://modules/mail_intake.parsers.body" + }, + { + "module": "mail_intake.parsers.headers", + "resource": "doc://modules/mail_intake.parsers.headers" + }, + { + "module": "mail_intake.parsers.subject", + "resource": "doc://modules/mail_intake.parsers.subject" + } +] \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 7cb3020..06940f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,63 +4,64 @@ site_description: Format-agnostic document reading, parsing, and scraping framew theme: name: material palette: - - scheme: slate - primary: deep purple - accent: cyan + - scheme: slate + primary: deep purple + accent: cyan font: text: Inter code: JetBrains Mono features: - - navigation.tabs - - navigation.expand - - navigation.top - - navigation.instant - - content.code.copy - - content.code.annotate + - navigation.tabs + - navigation.expand + - navigation.top + - navigation.instant + - content.code.copy + - content.code.annotate 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 +- 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 nav: - - Home: mail_intake/index.md - - - Adapters: - - Base Adapter: mail_intake/adapters/base.md - - Gmail Adapter: mail_intake/adapters/gmail.md - - - Auth: - - Base Auth: mail_intake/auth/base.md - - Google Auth: mail_intake/auth/google.md - - - Credentials Store: - - Store: mail_intake/credentials/store.md - - Pickle: mail_intake/credentials/pickle.md - - Redis: mail_intake/credentials/redis.md - - - Mail Reader: mail_intake/ingestion/reader.md - - - Models: - - Message: mail_intake/models/message.md - - Thread: mail_intake/models/thread.md - - - Parsers: - - Body: mail_intake/parsers/body.md - - Headers: mail_intake/parsers/headers.md - - Subject: mail_intake/parsers/subject.md - - - Config: mail_intake/config.md - - Exceptions: mail_intake/exceptions.md +- Home: mail_intake/index.md +- Core API: + - mail_intake/ingestion/index.md + - mail_intake/ingestion/reader.md +- Domain Models: + - mail_intake/models/index.md + - mail_intake/models/message.md + - mail_intake/models/thread.md +- Provider Adapters: + - mail_intake/adapters/index.md + - mail_intake/adapters/base.md + - mail_intake/adapters/gmail.md +- Authentication & Storage: + - 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: + - mail_intake/parsers/index.md + - mail_intake/parsers/body.md + - mail_intake/parsers/headers.md + - mail_intake/parsers/subject.md +- Configuration & Errors: + - mail_intake/config.md + - mail_intake/exceptions.md diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 860f640..0000000 --- a/requirements.txt +++ /dev/null @@ -1,17 +0,0 @@ -beautifulsoup4==4.12.0 -google-api-python-client==2.187.0 -google-auth-oauthlib==1.2.3 -types-beautifulsoup4 - -# Test Packages -pytest==7.4.0 -pytest-asyncio==0.21.0 -pytest-cov==4.1.0 - -# Doc Packages -mkdocs==1.6.1 -mkdocs-material==9.6.23 -neoteroi-mkdocs==1.1.3 -pymdown-extensions==10.16.1 -mkdocstrings==1.0.0 -mkdocstrings-python==2.0.1