From 371b74806f53eef6432f286693cfee65640281c1 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 17 Oct 2026 02:16:46 +0530 Subject: [PATCH] chore(release): 0.0.3 Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.3 --- .drone.yml | 74 +- .gitignore | 8 +- CHANGELOG.md | 33 + LICENSE | 21 + docforge.nav.yml | 47 +- docs/{ => lib}/adapters/base.md | 0 docs/{ => lib}/adapters/gmail.md | 0 docs/{ => lib}/adapters/index.md | 0 docs/{ => lib}/auth/base.md | 0 docs/{ => lib}/auth/google.md | 0 docs/{ => lib}/auth/index.md | 0 docs/{ => lib}/config.md | 0 docs/{ => lib}/credentials/index.md | 0 docs/{ => lib}/credentials/pickle.md | 0 docs/{ => lib}/credentials/redis.md | 0 docs/{ => lib}/credentials/store.md | 0 docs/{ => lib}/exceptions.md | 0 docs/{ => lib}/index.md | 0 docs/{ => lib}/ingestion/index.md | 0 docs/{ => lib}/ingestion/reader.md | 0 docs/{ => lib}/models/index.md | 0 docs/{ => lib}/models/message.md | 0 docs/{ => lib}/models/thread.md | 0 docs/{ => lib}/parsers/body.md | 0 docs/{ => lib}/parsers/headers.md | 0 docs/{ => lib}/parsers/index.md | 0 docs/{ => lib}/parsers/subject.md | 0 {mcp_docs => docs/mcp}/index.json | 2 +- .../modules/mail_intake.adapters.base.json | 39 + .../modules/mail_intake.adapters.gmail.json | 99 +- .../mcp}/modules/mail_intake.adapters.json | 180 ++-- .../mcp}/modules/mail_intake.auth.base.json | 32 +- .../mcp}/modules/mail_intake.auth.google.json | 69 +- .../mcp}/modules/mail_intake.auth.json | 115 +-- .../mcp}/modules/mail_intake.config.json | 16 +- .../mcp}/modules/mail_intake.credentials.json | 176 +--- .../mail_intake.credentials.pickle.json | 41 +- .../mail_intake.credentials.redis.json | 48 +- .../mail_intake.credentials.store.json | 45 +- .../mcp}/modules/mail_intake.exceptions.json | 10 +- .../mcp}/modules/mail_intake.ingestion.json | 140 ++- .../modules/mail_intake.ingestion.reader.json | 132 ++- .../mcp}/modules/mail_intake.json | 867 +++++------------- .../mcp}/modules/mail_intake.models.json | 130 +-- .../modules/mail_intake.models.message.json | 30 +- .../modules/mail_intake.models.thread.json | 66 +- .../mcp/modules/mail_intake.parsers.body.json | 23 + .../modules/mail_intake.parsers.headers.json | 23 + .../mcp}/modules/mail_intake.parsers.json | 100 +- .../modules/mail_intake.parsers.subject.json | 9 +- docs/mcp/nav.json | 90 ++ mkdocs.yml => docs/mkdocs.lib.yml | 48 +- docs/mkdocs.wiki.yml | 69 ++ docs/wiki/01_overview.md | 91 ++ docs/wiki/02_how_to_use.md | 105 +++ docs/wiki/03_extending.md | 106 +++ docs/wiki/04_development.md | 88 ++ docs/wiki/index.md | 71 ++ mail_intake/__init__.py | 1 - mail_intake/__init__.pyi | 8 +- mail_intake/adapters/base.py | 19 +- mail_intake/adapters/base.pyi | 9 +- mail_intake/adapters/gmail.py | 31 +- mail_intake/adapters/gmail.pyi | 14 +- mail_intake/auth/google.py | 4 +- mail_intake/auth/google.pyi | 8 +- mail_intake/config.py | 5 +- mail_intake/config.pyi | 15 +- mail_intake/credentials/__init__.pyi | 2 +- mail_intake/credentials/pickle.py | 6 +- mail_intake/credentials/pickle.pyi | 5 +- mail_intake/credentials/redis.py | 29 +- mail_intake/credentials/redis.pyi | 17 +- mail_intake/credentials/store.py | 7 +- mail_intake/credentials/store.pyi | 4 +- mail_intake/exceptions.py | 6 +- mail_intake/ingestion/reader.py | 19 +- mail_intake/ingestion/reader.pyi | 6 +- mail_intake/models/message.py | 5 +- mail_intake/models/message.pyi | 18 +- mail_intake/models/thread.py | 5 +- mail_intake/models/thread.pyi | 17 +- mail_intake/parsers/__init__.pyi | 2 +- mail_intake/parsers/body.py | 12 +- mail_intake/parsers/body.pyi | 4 +- mail_intake/parsers/headers.py | 16 +- mail_intake/parsers/headers.pyi | 6 +- mail_intake/parsers/subject.py | 1 - mail_intake/py.typed | 0 .../modules/mail_intake.adapters.base.json | 74 -- .../modules/mail_intake.parsers.body.json | 58 -- .../modules/mail_intake.parsers.headers.json | 51 -- mcp_docs/nav.json | 90 -- pyproject.toml | 118 ++- tests/unit/test_models.py | 5 +- tests/unit/test_parsers.py | 16 +- 96 files changed, 1756 insertions(+), 2200 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 LICENSE rename docs/{ => lib}/adapters/base.md (100%) rename docs/{ => lib}/adapters/gmail.md (100%) rename docs/{ => lib}/adapters/index.md (100%) rename docs/{ => lib}/auth/base.md (100%) rename docs/{ => lib}/auth/google.md (100%) rename docs/{ => lib}/auth/index.md (100%) rename docs/{ => lib}/config.md (100%) rename docs/{ => lib}/credentials/index.md (100%) rename docs/{ => lib}/credentials/pickle.md (100%) rename docs/{ => lib}/credentials/redis.md (100%) rename docs/{ => lib}/credentials/store.md (100%) rename docs/{ => lib}/exceptions.md (100%) rename docs/{ => lib}/index.md (100%) rename docs/{ => lib}/ingestion/index.md (100%) rename docs/{ => lib}/ingestion/reader.md (100%) rename docs/{ => lib}/models/index.md (100%) rename docs/{ => lib}/models/message.md (100%) rename docs/{ => lib}/models/thread.md (100%) rename docs/{ => lib}/parsers/body.md (100%) rename docs/{ => lib}/parsers/headers.md (100%) rename docs/{ => lib}/parsers/index.md (100%) rename docs/{ => lib}/parsers/subject.md (100%) rename {mcp_docs => docs/mcp}/index.json (73%) create mode 100644 docs/mcp/modules/mail_intake.adapters.base.json rename {mcp_docs => docs/mcp}/modules/mail_intake.adapters.gmail.json (65%) rename {mcp_docs => docs/mcp}/modules/mail_intake.adapters.json (63%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.base.json (68%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.google.json (68%) rename {mcp_docs => docs/mcp}/modules/mail_intake.auth.json (72%) rename {mcp_docs => docs/mcp}/modules/mail_intake.config.json (81%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.json (68%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.pickle.json (68%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.redis.json (70%) rename {mcp_docs => docs/mcp}/modules/mail_intake.credentials.store.json (62%) rename {mcp_docs => docs/mcp}/modules/mail_intake.exceptions.json (70%) rename {mcp_docs => docs/mcp}/modules/mail_intake.ingestion.json (67%) rename {mcp_docs => docs/mcp}/modules/mail_intake.ingestion.reader.json (65%) rename {mcp_docs => docs/mcp}/modules/mail_intake.json (68%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.json (70%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.message.json (76%) rename {mcp_docs => docs/mcp}/modules/mail_intake.models.thread.json (66%) create mode 100644 docs/mcp/modules/mail_intake.parsers.body.json create mode 100644 docs/mcp/modules/mail_intake.parsers.headers.json rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.json (60%) rename {mcp_docs => docs/mcp}/modules/mail_intake.parsers.subject.json (80%) create mode 100644 docs/mcp/nav.json rename mkdocs.yml => docs/mkdocs.lib.yml (91%) create mode 100644 docs/mkdocs.wiki.yml create mode 100644 docs/wiki/01_overview.md create mode 100644 docs/wiki/02_how_to_use.md create mode 100644 docs/wiki/03_extending.md create mode 100644 docs/wiki/04_development.md create mode 100644 docs/wiki/index.md create mode 100644 mail_intake/py.typed delete mode 100644 mcp_docs/modules/mail_intake.adapters.base.json delete mode 100644 mcp_docs/modules/mail_intake.parsers.body.json delete mode 100644 mcp_docs/modules/mail_intake.parsers.headers.json delete mode 100644 mcp_docs/nav.json diff --git a/.drone.yml b/.drone.yml index ddd0ac4..122d0f6 100644 --- a/.drone.yml +++ b/.drone.yml @@ -1,3 +1,21 @@ +# Drone standard β€” Type A: PyPI package +# +# Canonical pipeline for internal Python libraries that ship a wheel/sdist to +# the private index (dagpipe, doc-forge, hexa, mail-intake, mongo-ops, +# omniread, openapi-first, py-jwt). +# +# Two pipelines ship together: +# build-and-publish-pypi β€” tag-triggered build + quality gate + publish. +# backfill-pypi-from-tags β€” custom-triggered replay of every git tag that is +# missing from the index (disaster recovery). +# +# Secrets (Drone): PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD. +# Copy to /.drone.yml unchanged; the package name and version are read +# from pyproject.toml, so no per-repo edits are required. +# +# Version guard: the tag build fails unless the git tag equals the version in +# pyproject.toml (see the versioning standard). This stops a tag from looking +# like a release while silently publishing nothing. --- kind: pipeline type: docker @@ -23,20 +41,46 @@ steps: commands: - PACKAGE_NAME=$(grep -E '^name\s*=' pyproject.toml | head -1 | cut -d'"' -f2) - VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | cut -d'"' -f2) - - echo "πŸ” Checking if $PACKAGE_NAME==$VERSION exists on $PIP_REPO_URL ..." - | - if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -q "$VERSION"; then - echo "βœ… $PACKAGE_NAME==$VERSION already exists β€” skipping build." + if [ "$DRONE_TAG" != "$VERSION" ]; then + echo "Tag '$DRONE_TAG' does not match pyproject version '$VERSION'; refusing to publish." + exit 1 + fi + - echo "Checking if $PACKAGE_NAME==$VERSION exists on $PIP_REPO_URL ..." + - | + if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -qE "${PACKAGE_NAME}-${VERSION}(-|\.tar\.gz|\.whl)"; then + echo "$PACKAGE_NAME==$VERSION already exists; skipping build." exit 78 else - echo "πŸ†• New version detected: $PACKAGE_NAME==$VERSION" + echo "New version detected: $PACKAGE_NAME==$VERSION" fi + - name: quality-gate + image: python:3.13-slim + environment: + PIP_REPO_URL: + from_secret: PIP_REPO_URL + PIP_USERNAME: + from_secret: PIP_USERNAME + PIP_PASSWORD: + from_secret: PIP_PASSWORD + commands: + - pip install --upgrade pip build + - | + AUTH_URL="https://${PIP_USERNAME}:${PIP_PASSWORD}@$(echo "${PIP_REPO_URL#*://}" | sed 's:/*$::')/simple" + pip install --index-url "$AUTH_URL" --extra-index-url https://pypi.org/simple/ -U ".[dev]" "pydoclint>=0.9.1" + - echo "Running quality gate..." + - python -m black --check . + - python -m ruff check . + - python -m mypy + - pydoclint . + - python -m pytest + - name: build-package image: python:3.13-slim commands: - pip install --upgrade pip build - - echo "πŸ“¦ Building Python package..." + - echo "Building Python package..." - python -m build - ls -l dist @@ -51,7 +95,7 @@ steps: from_secret: PIP_PASSWORD commands: - pip install --upgrade twine - - echo "πŸš€ Uploading to private PyPI at $PIP_REPO_URL ..." + - echo "Uploading to private PyPI at $PIP_REPO_URL ..." - | twine upload \ --repository-url "$PIP_REPO_URL" \ @@ -98,25 +142,31 @@ steps: set -e PACKAGE_NAME=$(grep -E '^name\s*=' pyproject.toml | cut -d'"' -f2) - echo "πŸ“¦ Package: $PACKAGE_NAME" + echo "Package: $PACKAGE_NAME" for TAG in $(git tag --sort=version:refname); do VERSION="$TAG" - echo "πŸ” Version: $VERSION" + echo "Version: $VERSION" if curl -fsSL -u "$PIP_USERNAME:$PIP_PASSWORD" \ - "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -q "$VERSION"; then - echo "⏭️ Exists, skipping" + "$PIP_REPO_URL/simple/$PACKAGE_NAME/" | grep -qE "${PACKAGE_NAME}-${VERSION}(-|\.tar\.gz|\.whl)"; then + echo "Exists, skipping" continue fi git checkout --force "$TAG" - echo "πŸ—οΈ Building $VERSION" + TAG_VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | cut -d'"' -f2) + if [ "$TAG" != "$TAG_VERSION" ]; then + echo "Tag $TAG != pyproject version $TAG_VERSION at that commit; skipping" + continue + fi + + echo "Building $VERSION" rm -rf dist python -m build - echo "⬆️ Uploading $VERSION" + echo "Uploading $VERSION" twine upload \ --repository-url "$PIP_REPO_URL" \ -u "$PIP_USERNAME" \ diff --git a/.gitignore b/.gitignore index 2209baf..9bb4831 100644 --- a/.gitignore +++ b/.gitignore @@ -25,10 +25,17 @@ env/ htmlcov/ coverage.xml +# Lint / type checking +.mypy_cache/ +.ruff_cache/ + # Environment variables .env .env.local +# Docs build artifacts +site + # OS .DS_Store Thumbs.db @@ -38,7 +45,6 @@ Thumbs.db *.swo *~ *.tmp -site # Credentials client_secret_*.json diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bac7600 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.0.3] - 2026-10-17 + +### Added +- `py.typed` marker for PEP 561 type information. +- Hand-written wiki, plus doc-forge-generated API reference under `docs/lib` + and MCP bundle under `docs/mcp` (per-kind MkDocs configs). +- MIT `LICENSE`. + +### Changed +- Adopted the standard Type A PyPI CI pipeline: a `tag == version` guard and a + quality gate (black, ruff, mypy, pydoclint, pytest). +- Standardized `pyproject.toml` (canonical packaging, lint tool config, extras) + with a shared Google-style `[tool.pydoclint]` configuration. +- Google-style (GSDFC) docstrings across the public API; legacy typing + modernised to match signatures. +- `fetch_emails.py` debug script excluded from black/ruff scans. + +### Fixed +- Regression test for immutable config models raises `AssertionError` instead + of a bare `assert False`. +- Stub fixes for typed API surfaces. + +[Unreleased]: https://git.aetoskia.com/aetos/mail-intake/compare/0.0.3...HEAD +[0.0.3]: https://git.aetoskia.com/aetos/mail-intake/compare/0.0.2...0.0.3 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..87328b2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Aetoskia Platform + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/docforge.nav.yml b/docforge.nav.yml index 26c6d7c..99d6eda 100644 --- a/docforge.nav.yml +++ b/docforge.nav.yml @@ -1,29 +1,32 @@ -home: index.md +home: lib/index.md groups: Core API: - - ingestion/index.md - - ingestion/reader.md + - lib/ingestion/index.md + - lib/ingestion/reader.md Domain Models: - - models/index.md - - models/message.md - - models/thread.md + - lib/models/index.md + - lib/models/message.md + - lib/models/thread.md Provider Adapters: - - adapters/index.md - - adapters/base.md - - adapters/gmail.md + - lib/adapters/index.md + - lib/adapters/base.md + - lib/adapters/gmail.md Authentication & Storage: - - auth/index.md - - auth/base.md - - auth/google.md - - credentials/index.md - - credentials/store.md - - credentials/pickle.md - - credentials/redis.md + - lib/auth/index.md + - lib/auth/base.md + - lib/auth/google.md + - lib/credentials/index.md + - lib/credentials/store.md + - lib/credentials/pickle.md + - lib/credentials/redis.md Normalization & Parsing: - - parsers/index.md - - parsers/body.md - - parsers/headers.md - - parsers/subject.md + - lib/parsers/index.md + - lib/parsers/body.md + - lib/parsers/headers.md + - lib/parsers/subject.md Configuration & Errors: - - config.md - - exceptions.md + - lib/config.md + - lib/exceptions.md +icon: + logo: material/inbox + repo: fontawesome/brands/github \ No newline at end of file diff --git a/docs/adapters/base.md b/docs/lib/adapters/base.md similarity index 100% rename from docs/adapters/base.md rename to docs/lib/adapters/base.md diff --git a/docs/adapters/gmail.md b/docs/lib/adapters/gmail.md similarity index 100% rename from docs/adapters/gmail.md rename to docs/lib/adapters/gmail.md diff --git a/docs/adapters/index.md b/docs/lib/adapters/index.md similarity index 100% rename from docs/adapters/index.md rename to docs/lib/adapters/index.md diff --git a/docs/auth/base.md b/docs/lib/auth/base.md similarity index 100% rename from docs/auth/base.md rename to docs/lib/auth/base.md diff --git a/docs/auth/google.md b/docs/lib/auth/google.md similarity index 100% rename from docs/auth/google.md rename to docs/lib/auth/google.md diff --git a/docs/auth/index.md b/docs/lib/auth/index.md similarity index 100% rename from docs/auth/index.md rename to docs/lib/auth/index.md diff --git a/docs/config.md b/docs/lib/config.md similarity index 100% rename from docs/config.md rename to docs/lib/config.md diff --git a/docs/credentials/index.md b/docs/lib/credentials/index.md similarity index 100% rename from docs/credentials/index.md rename to docs/lib/credentials/index.md diff --git a/docs/credentials/pickle.md b/docs/lib/credentials/pickle.md similarity index 100% rename from docs/credentials/pickle.md rename to docs/lib/credentials/pickle.md diff --git a/docs/credentials/redis.md b/docs/lib/credentials/redis.md similarity index 100% rename from docs/credentials/redis.md rename to docs/lib/credentials/redis.md diff --git a/docs/credentials/store.md b/docs/lib/credentials/store.md similarity index 100% rename from docs/credentials/store.md rename to docs/lib/credentials/store.md diff --git a/docs/exceptions.md b/docs/lib/exceptions.md similarity index 100% rename from docs/exceptions.md rename to docs/lib/exceptions.md diff --git a/docs/index.md b/docs/lib/index.md similarity index 100% rename from docs/index.md rename to docs/lib/index.md diff --git a/docs/ingestion/index.md b/docs/lib/ingestion/index.md similarity index 100% rename from docs/ingestion/index.md rename to docs/lib/ingestion/index.md diff --git a/docs/ingestion/reader.md b/docs/lib/ingestion/reader.md similarity index 100% rename from docs/ingestion/reader.md rename to docs/lib/ingestion/reader.md diff --git a/docs/models/index.md b/docs/lib/models/index.md similarity index 100% rename from docs/models/index.md rename to docs/lib/models/index.md diff --git a/docs/models/message.md b/docs/lib/models/message.md similarity index 100% rename from docs/models/message.md rename to docs/lib/models/message.md diff --git a/docs/models/thread.md b/docs/lib/models/thread.md similarity index 100% rename from docs/models/thread.md rename to docs/lib/models/thread.md diff --git a/docs/parsers/body.md b/docs/lib/parsers/body.md similarity index 100% rename from docs/parsers/body.md rename to docs/lib/parsers/body.md diff --git a/docs/parsers/headers.md b/docs/lib/parsers/headers.md similarity index 100% rename from docs/parsers/headers.md rename to docs/lib/parsers/headers.md diff --git a/docs/parsers/index.md b/docs/lib/parsers/index.md similarity index 100% rename from docs/parsers/index.md rename to docs/lib/parsers/index.md diff --git a/docs/parsers/subject.md b/docs/lib/parsers/subject.md similarity index 100% rename from docs/parsers/subject.md rename to docs/lib/parsers/subject.md diff --git a/mcp_docs/index.json b/docs/mcp/index.json similarity index 73% rename from mcp_docs/index.json rename to docs/mcp/index.json index d4d506d..2685f38 100644 --- a/mcp_docs/index.json +++ b/docs/mcp/index.json @@ -1,5 +1,5 @@ { - "project": "mail_intake", + "project": "Mail Intake", "type": "docforge-model", "modules_count": 22, "source": "docforge" diff --git a/docs/mcp/modules/mail_intake.adapters.base.json b/docs/mcp/modules/mail_intake.adapters.base.json new file mode 100644 index 0000000..2e966cf --- /dev/null +++ b/docs/mcp/modules/mail_intake.adapters.base.json @@ -0,0 +1,39 @@ +{ + "module": "mail_intake.adapters.base", + "content": { + "path": "mail_intake.adapters.base", + "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.", + "objects": { + "MailIntakeAdapter": { + "name": "MailIntakeAdapter", + "kind": "class", + "path": "mail_intake.adapters.base.MailIntakeAdapter", + "signature": null, + "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", + "members": { + "iter_message_refs": { + "name": "iter_message_refs", + "kind": "function", + "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + }, + "fetch_message": { + "name": "fetch_message", + "kind": "function", + "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + }, + "fetch_thread": { + "name": "fetch_thread", + "kind": "function", + "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." + } + } + } + } + } +} \ No newline at end of file diff --git a/mcp_docs/modules/mail_intake.adapters.gmail.json b/docs/mcp/modules/mail_intake.adapters.gmail.json similarity index 65% rename from mcp_docs/modules/mail_intake.adapters.gmail.json rename to docs/mcp/modules/mail_intake.adapters.gmail.json index 7dcb866..d23b381 100644 --- a/mcp_docs/modules/mail_intake.adapters.gmail.json +++ b/docs/mcp/modules/mail_intake.adapters.gmail.json @@ -4,68 +4,49 @@ "path": "mail_intake.adapters.gmail", "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.", "objects": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." + } + } + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider", + "signature": null, + "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", + "members": { + "get_credentials": { + "name": "get_credentials", + "kind": "function", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", + "signature": "get_credentials()", + "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } }, @@ -73,30 +54,14 @@ "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", + "signature": null, "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, - "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\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", - "members": { - "get_credentials": { - "name": "get_credentials", - "kind": "function", - "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", - "signature": "", - "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." - } - } - }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -104,28 +69,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } diff --git a/mcp_docs/modules/mail_intake.adapters.json b/docs/mcp/modules/mail_intake.adapters.json similarity index 63% rename from mcp_docs/modules/mail_intake.adapters.json rename to docs/mcp/modules/mail_intake.adapters.json index 7fc236c..c2bbab4 100644 --- a/mcp_docs/modules/mail_intake.adapters.json +++ b/docs/mcp/modules/mail_intake.adapters.json @@ -8,29 +8,29 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.MailIntakeAdapter", - "signature": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -38,36 +38,36 @@ "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.MailIntakeGmailAdapter", - "signature": "", + "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { "name": "service", "kind": "attribute", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service", - "signature": "", - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "signature": null, + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } }, @@ -78,68 +78,33 @@ "signature": null, "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } } @@ -152,68 +117,49 @@ "signature": null, "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." + } + } + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider", + "signature": null, + "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", + "members": { + "get_credentials": { + "name": "get_credentials", + "kind": "function", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", + "signature": "get_credentials()", + "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } }, @@ -221,30 +167,14 @@ "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", + "signature": null, "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, - "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\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", - "members": { - "get_credentials": { - "name": "get_credentials", - "kind": "function", - "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", - "signature": "", - "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." - } - } - }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -252,28 +182,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } diff --git a/mcp_docs/modules/mail_intake.auth.base.json b/docs/mcp/modules/mail_intake.auth.base.json similarity index 68% rename from mcp_docs/modules/mail_intake.auth.base.json rename to docs/mcp/modules/mail_intake.auth.base.json index db333d6..0072a2d 100644 --- a/mcp_docs/modules/mail_intake.auth.base.json +++ b/docs/mcp/modules/mail_intake.auth.base.json @@ -4,34 +4,6 @@ "path": "mail_intake.auth.base", "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.", "objects": { - "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", @@ -43,14 +15,14 @@ "name": "MailIntakeAuthProvider", "kind": "class", "path": "mail_intake.auth.base.MailIntakeAuthProvider", - "signature": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials() -> T", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } diff --git a/mcp_docs/modules/mail_intake.auth.google.json b/docs/mcp/modules/mail_intake.auth.google.json similarity index 68% rename from mcp_docs/modules/mail_intake.auth.google.json rename to docs/mcp/modules/mail_intake.auth.google.json index 7b8baa2..357f621 100644 --- a/mcp_docs/modules/mail_intake.auth.google.json +++ b/docs/mcp/modules/mail_intake.auth.google.json @@ -4,60 +4,18 @@ "path": "mail_intake.auth.google", "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.", "objects": { - "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": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -66,28 +24,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.auth.google.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -96,14 +54,14 @@ "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.auth.google.MailIntakeAuthError", - "signature": "", + "signature": null, "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeGoogleAuth": { "name": "MailIntakeGoogleAuth", "kind": "class", "path": "mail_intake.auth.google.MailIntakeGoogleAuth", - "signature": "", + "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])", "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n **Responsibilities:**\n\n - Load cached credentials from a credential store when available.\n - Refresh expired credentials when possible.\n - Initiate an interactive OAuth flow only when required.\n - Persist refreshed or newly obtained credentials via the store.\n\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n internal state.", "members": { "credentials_path": { @@ -131,17 +89,10 @@ "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials", - "signature": "", + "signature": "get_credentials() -> Any", "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.auth.google.Any", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.auth.json b/docs/mcp/modules/mail_intake.auth.json similarity index 72% rename from mcp_docs/modules/mail_intake.auth.json rename to docs/mcp/modules/mail_intake.auth.json index 0a4263b..4a999a3 100644 --- a/mcp_docs/modules/mail_intake.auth.json +++ b/docs/mcp/modules/mail_intake.auth.json @@ -8,14 +8,14 @@ "name": "MailIntakeAuthProvider", "kind": "class", "path": "mail_intake.auth.MailIntakeAuthProvider", - "signature": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -24,35 +24,35 @@ "name": "MailIntakeGoogleAuth", "kind": "class", "path": "mail_intake.auth.MailIntakeGoogleAuth", - "signature": "", + "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])", "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n **Responsibilities:**\n\n - Load cached credentials from a credential store when available.\n - Refresh expired credentials when possible.\n - Initiate an interactive OAuth flow only when required.\n - Persist refreshed or newly obtained credentials via the store.\n\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n internal state.", "members": { "credentials_path": { "name": "credentials_path", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.credentials_path", - "signature": "", + "signature": null, "docstring": null }, "store": { "name": "store", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.store", - "signature": "", + "signature": null, "docstring": null }, "scopes": { "name": "scopes", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes", - "signature": "", + "signature": null, "docstring": null }, "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use." } } @@ -64,34 +64,6 @@ "signature": null, "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.", "members": { - "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", @@ -103,14 +75,14 @@ "name": "MailIntakeAuthProvider", "kind": "class", "path": "mail_intake.auth.base.MailIntakeAuthProvider", - "signature": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials() -> T", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -124,60 +96,18 @@ "signature": null, "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.", "members": { - "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": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -186,28 +116,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.auth.google.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -216,14 +146,14 @@ "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.auth.google.MailIntakeAuthError", - "signature": "", + "signature": null, "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeGoogleAuth": { "name": "MailIntakeGoogleAuth", "kind": "class", "path": "mail_intake.auth.google.MailIntakeGoogleAuth", - "signature": "", + "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])", "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n **Responsibilities:**\n\n - Load cached credentials from a credential store when available.\n - Refresh expired credentials when possible.\n - Initiate an interactive OAuth flow only when required.\n - Persist refreshed or newly obtained credentials via the store.\n\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n internal state.", "members": { "credentials_path": { @@ -251,17 +181,10 @@ "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials", - "signature": "", + "signature": "get_credentials() -> Any", "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.auth.google.Any", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.config.json b/docs/mcp/modules/mail_intake.config.json similarity index 81% rename from mcp_docs/modules/mail_intake.config.json rename to docs/mcp/modules/mail_intake.config.json index e027f04..6feb14a 100644 --- a/mcp_docs/modules/mail_intake.config.json +++ b/docs/mcp/modules/mail_intake.config.json @@ -4,25 +4,11 @@ "path": "mail_intake.config", "docstring": "# Summary\n\nGlobal 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": "", + "signature": "MailIntakeConfig(provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: str | None = ..., token_path: str | None = ...)", "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.", "members": { "provider": { diff --git a/mcp_docs/modules/mail_intake.credentials.json b/docs/mcp/modules/mail_intake.credentials.json similarity index 68% rename from mcp_docs/modules/mail_intake.credentials.json rename to docs/mcp/modules/mail_intake.credentials.json index df9d409..0c13fc5 100644 --- a/mcp_docs/modules/mail_intake.credentials.json +++ b/docs/mcp/modules/mail_intake.credentials.json @@ -8,28 +8,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -38,35 +38,35 @@ "name": "PickleCredentialStore", "kind": "class", "path": "mail_intake.credentials.PickleCredentialStore", - "signature": "", + "signature": "PickleCredentialStore(path: str)", "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n **Guarantees:**\n\n - Stores credentials on the local filesystem.\n - Uses `pickle` for serialization and deserialization.\n - Does not provide encryption, locking, or concurrency guarantees.\n\n **Constraints:**\n\n - Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.", "members": { "path": { "name": "path", "kind": "attribute", "path": "mail_intake.credentials.PickleCredentialStore.path", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.load", - "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "signature": "load()", + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials at the configured path are overwritten" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n **Lifecycle:**\n\n - This method deletes the credential file if it exists and should be treated as an idempotent operation" } } @@ -75,63 +75,63 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.RedisCredentialStore", - "signature": "", + "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { "name": "redis", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.redis", - "signature": "", + "signature": null, "docstring": null }, "key": { "name": "key", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.key", - "signature": "", + "signature": null, "docstring": null }, "serialize": { "name": "serialize", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.serialize", - "signature": "", + "signature": null, "docstring": null }, "deserialize": { "name": "deserialize", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.deserialize", - "signature": "", + "signature": null, "docstring": null }, "ttl_seconds": { "name": "ttl_seconds", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.ttl_seconds", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "load()", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } @@ -143,53 +143,32 @@ "signature": null, "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.", "members": { - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -205,7 +184,7 @@ "name": "PickleCredentialStore", "kind": "class", "path": "mail_intake.credentials.pickle.PickleCredentialStore", - "signature": "", + "signature": "PickleCredentialStore(path: str)", "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n **Guarantees:**\n\n - Stores credentials on the local filesystem.\n - Uses `pickle` for serialization and deserialization.\n - Does not provide encryption, locking, or concurrency guarantees.\n\n **Constraints:**\n\n - Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.", "members": { "path": { @@ -219,21 +198,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", - "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "signature": "load() -> T | None", + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials at the configured path are overwritten" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n **Lifecycle:**\n\n - This method deletes the credential file if it exists and should be treated as an idempotent operation" } } @@ -247,53 +226,32 @@ "signature": null, "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "members": { - "Optional": { - "name": "Optional", - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -309,7 +267,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -351,31 +309,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "load() -> T | None", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } }, @@ -386,41 +337,6 @@ "signature": null, "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategiesβ€”such as local files, in-memory caches, distributed stores,\nor secrets managersβ€”without coupling authentication logic to any\nspecific storage mechanism.", "members": { - "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", @@ -432,28 +348,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load() -> T | None", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } diff --git a/mcp_docs/modules/mail_intake.credentials.pickle.json b/docs/mcp/modules/mail_intake.credentials.pickle.json similarity index 68% rename from mcp_docs/modules/mail_intake.credentials.pickle.json rename to docs/mcp/modules/mail_intake.credentials.pickle.json index 16e8c40..f6bb66d 100644 --- a/mcp_docs/modules/mail_intake.credentials.pickle.json +++ b/docs/mcp/modules/mail_intake.credentials.pickle.json @@ -4,53 +4,32 @@ "path": "mail_intake.credentials.pickle", "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.", "objects": { - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -66,7 +45,7 @@ "name": "PickleCredentialStore", "kind": "class", "path": "mail_intake.credentials.pickle.PickleCredentialStore", - "signature": "", + "signature": "PickleCredentialStore(path: str)", "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n **Guarantees:**\n\n - Stores credentials on the local filesystem.\n - Uses `pickle` for serialization and deserialization.\n - Does not provide encryption, locking, or concurrency guarantees.\n\n **Constraints:**\n\n - Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.", "members": { "path": { @@ -80,21 +59,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", - "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "signature": "load() -> T | None", + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials at the configured path are overwritten" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n **Lifecycle:**\n\n - This method deletes the credential file if it exists and should be treated as an idempotent operation" } } diff --git a/mcp_docs/modules/mail_intake.credentials.redis.json b/docs/mcp/modules/mail_intake.credentials.redis.json similarity index 70% rename from mcp_docs/modules/mail_intake.credentials.redis.json rename to docs/mcp/modules/mail_intake.credentials.redis.json index f2bbbfa..4b1d6b9 100644 --- a/mcp_docs/modules/mail_intake.credentials.redis.json +++ b/docs/mcp/modules/mail_intake.credentials.redis.json @@ -4,53 +4,32 @@ "path": "mail_intake.credentials.redis", "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "objects": { - "Optional": { - "name": "Optional", - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -66,7 +45,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -108,31 +87,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "load() -> T | None", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.credentials.store.json b/docs/mcp/modules/mail_intake.credentials.store.json similarity index 62% rename from mcp_docs/modules/mail_intake.credentials.store.json rename to docs/mcp/modules/mail_intake.credentials.store.json index efc7fed..d777c89 100644 --- a/mcp_docs/modules/mail_intake.credentials.store.json +++ b/docs/mcp/modules/mail_intake.credentials.store.json @@ -4,41 +4,6 @@ "path": "mail_intake.credentials.store", "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategiesβ€”such as local files, in-memory caches, distributed stores,\nor secrets managersβ€”without coupling authentication logic to any\nspecific storage mechanism.", "objects": { - "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", @@ -50,28 +15,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load() -> T | None", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } diff --git a/mcp_docs/modules/mail_intake.exceptions.json b/docs/mcp/modules/mail_intake.exceptions.json similarity index 70% rename from mcp_docs/modules/mail_intake.exceptions.json rename to docs/mcp/modules/mail_intake.exceptions.json index 824d2f6..ef3ec40 100644 --- a/mcp_docs/modules/mail_intake.exceptions.json +++ b/docs/mcp/modules/mail_intake.exceptions.json @@ -2,34 +2,34 @@ "module": "mail_intake.exceptions", "content": { "path": "mail_intake.exceptions", - "docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", + "docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", "objects": { "MailIntakeError": { "name": "MailIntakeError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeError", - "signature": "", + "signature": null, "docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures" }, "MailIntakeAuthError": { "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAuthError", - "signature": "", + "signature": null, "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeAdapterError": { "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAdapterError", - "signature": "", + "signature": null, "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, "MailIntakeParsingError": { "name": "MailIntakeParsingError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeParsingError", - "signature": "", + "signature": null, "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." } } diff --git a/mcp_docs/modules/mail_intake.ingestion.json b/docs/mcp/modules/mail_intake.ingestion.json similarity index 67% rename from mcp_docs/modules/mail_intake.ingestion.json rename to docs/mcp/modules/mail_intake.ingestion.json index eb08b63..e59ba60 100644 --- a/mcp_docs/modules/mail_intake.ingestion.json +++ b/docs/mcp/modules/mail_intake.ingestion.json @@ -8,22 +8,22 @@ "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.MailIntakeReader", - "signature": "", + "signature": "MailIntakeReader(adapter: MailIntakeAdapter)", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_messages", - "signature": "", + "signature": "iter_messages(query: str)", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", - "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "signature": "iter_threads(query: str)", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } }, @@ -34,132 +34,111 @@ "signature": null, "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": null, + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeMessage", - "signature": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "docstring": "Message timestamp as a timezone-naive UTC datetime." }, "from_email": { "name": "from_email", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_email", - "signature": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "docstring": "Short provider-supplied preview snippet of the message." }, "raw_headers": { "name": "raw_headers", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.raw_headers", - "signature": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -168,108 +147,101 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier." }, "normalized_subject": { "name": "normalized_subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", - "signature": "", + "signature": null, "docstring": "Normalized subject line used to group related messages." }, "participants": { "name": "participants", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", - "signature": "", + "signature": null, "docstring": "Set of unique participant email addresses observed in the thread." }, "messages": { "name": "messages", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", - "signature": "", + "signature": null, "docstring": "Ordered list of messages belonging to this thread." }, "last_activity_at": { "name": "last_activity_at", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.last_activity_at", - "signature": "", + "signature": null, "docstring": "Timestamp of the most recent message in the thread." }, "add_message": { "name": "add_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage)", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } }, - "parse_headers": { - "name": "parse_headers", - "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" - }, - "extract_sender": { - "name": "extract_sender", - "kind": "function", - "path": "mail_intake.ingestion.reader.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" - }, "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:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any])", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "extract_sender(headers: dict[str, str])", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "parse_headers(raw_headers: list[dict[str, str]])", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", "kind": "function", "path": "mail_intake.ingestion.reader.normalize_subject", - "signature": "", + "signature": "normalize_subject(subject: str)", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "MailIntakeReader(adapter: MailIntakeAdapter)", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "iter_messages(query: str) -> Iterator[MailIntakeMessage]", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "signature": "iter_threads(query: str) -> Iterator[MailIntakeThread]", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } diff --git a/mcp_docs/modules/mail_intake.ingestion.reader.json b/docs/mcp/modules/mail_intake.ingestion.reader.json similarity index 65% rename from mcp_docs/modules/mail_intake.ingestion.reader.json rename to docs/mcp/modules/mail_intake.ingestion.reader.json index 0312193..2472acb 100644 --- a/mcp_docs/modules/mail_intake.ingestion.reader.json +++ b/docs/mcp/modules/mail_intake.ingestion.reader.json @@ -4,132 +4,111 @@ "path": "mail_intake.ingestion.reader", "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "objects": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": null, + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeMessage", - "signature": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "docstring": "Message timestamp as a timezone-naive UTC datetime." }, "from_email": { "name": "from_email", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_email", - "signature": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "docstring": "Short provider-supplied preview snippet of the message." }, "raw_headers": { "name": "raw_headers", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.raw_headers", - "signature": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -138,108 +117,101 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier." }, "normalized_subject": { "name": "normalized_subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", - "signature": "", + "signature": null, "docstring": "Normalized subject line used to group related messages." }, "participants": { "name": "participants", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", - "signature": "", + "signature": null, "docstring": "Set of unique participant email addresses observed in the thread." }, "messages": { "name": "messages", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", - "signature": "", + "signature": null, "docstring": "Ordered list of messages belonging to this thread." }, "last_activity_at": { "name": "last_activity_at", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.last_activity_at", - "signature": "", + "signature": null, "docstring": "Timestamp of the most recent message in the thread." }, "add_message": { "name": "add_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage)", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } }, - "parse_headers": { - "name": "parse_headers", - "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" - }, - "extract_sender": { - "name": "extract_sender", - "kind": "function", - "path": "mail_intake.ingestion.reader.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" - }, "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:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any])", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "extract_sender(headers: dict[str, str])", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "parse_headers(raw_headers: list[dict[str, str]])", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", "kind": "function", "path": "mail_intake.ingestion.reader.normalize_subject", - "signature": "", + "signature": "normalize_subject(subject: str)", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "MailIntakeReader(adapter: MailIntakeAdapter)", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "iter_messages(query: str) -> Iterator[MailIntakeMessage]", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "signature": "iter_threads(query: str) -> Iterator[MailIntakeThread]", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } diff --git a/mcp_docs/modules/mail_intake.json b/docs/mcp/modules/mail_intake.json similarity index 68% rename from mcp_docs/modules/mail_intake.json rename to docs/mcp/modules/mail_intake.json index 03d7213..fe3dba7 100644 --- a/mcp_docs/modules/mail_intake.json +++ b/docs/mcp/modules/mail_intake.json @@ -11,25 +11,11 @@ "signature": null, "docstring": "# Summary\n\nGlobal 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": "", + "signature": "MailIntakeConfig(provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: str | None = ..., token_path: str | None = ...)", "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.", "members": { "provider": { @@ -76,34 +62,34 @@ "kind": "module", "path": "mail_intake.exceptions", "signature": null, - "docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", + "docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.", "members": { "MailIntakeError": { "name": "MailIntakeError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeError", - "signature": "", + "signature": null, "docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures" }, "MailIntakeAuthError": { "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAuthError", - "signature": "", + "signature": null, "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeAdapterError": { "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeAdapterError", - "signature": "", + "signature": null, "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, "MailIntakeParsingError": { "name": "MailIntakeParsingError", "kind": "class", "path": "mail_intake.exceptions.MailIntakeParsingError", - "signature": "", + "signature": null, "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." } } @@ -119,29 +105,29 @@ "name": "MailIntakeAdapter", "kind": "class", "path": "mail_intake.adapters.MailIntakeAdapter", - "signature": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, @@ -149,36 +135,36 @@ "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.MailIntakeGmailAdapter", - "signature": "", + "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { "name": "service", "kind": "attribute", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service", - "signature": "", - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "signature": null, + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } }, @@ -189,68 +175,33 @@ "signature": null, "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } } @@ -263,68 +214,49 @@ "signature": null, "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." + } + } + }, + "MailIntakeAuthProvider": { + "name": "MailIntakeAuthProvider", + "kind": "class", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider", + "signature": null, + "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", + "members": { + "get_credentials": { + "name": "get_credentials", + "kind": "function", + "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", + "signature": "get_credentials()", + "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } }, @@ -332,30 +264,14 @@ "name": "MailIntakeAdapterError", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeAdapterError", - "signature": "", + "signature": null, "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses." }, - "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\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", - "members": { - "get_credentials": { - "name": "get_credentials", - "kind": "function", - "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials", - "signature": "", - "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." - } - } - }, "MailIntakeGmailAdapter": { "name": "MailIntakeGmailAdapter", "kind": "class", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", - "signature": "", + "signature": "MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider[Any], user_id: str = 'me')", "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.", "members": { "service": { @@ -363,28 +279,28 @@ "kind": "attribute", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "signature": null, - "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." + "docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized." }, "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "iter_message_refs(query: str) -> Iterator[dict[str, str]]", + "docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_message(message_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." + "signature": "fetch_thread(thread_id: str) -> dict[str, Any]", + "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error." } } } @@ -403,14 +319,14 @@ "name": "MailIntakeAuthProvider", "kind": "class", "path": "mail_intake.auth.MailIntakeAuthProvider", - "signature": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -419,35 +335,35 @@ "name": "MailIntakeGoogleAuth", "kind": "class", "path": "mail_intake.auth.MailIntakeGoogleAuth", - "signature": "", + "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])", "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n **Responsibilities:**\n\n - Load cached credentials from a credential store when available.\n - Refresh expired credentials when possible.\n - Initiate an interactive OAuth flow only when required.\n - Persist refreshed or newly obtained credentials via the store.\n\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n internal state.", "members": { "credentials_path": { "name": "credentials_path", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.credentials_path", - "signature": "", + "signature": null, "docstring": null }, "store": { "name": "store", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.store", - "signature": "", + "signature": null, "docstring": null }, "scopes": { "name": "scopes", "kind": "attribute", "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes", - "signature": "", + "signature": null, "docstring": null }, "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use." } } @@ -459,34 +375,6 @@ "signature": null, "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.", "members": { - "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", @@ -498,14 +386,14 @@ "name": "MailIntakeAuthProvider", "kind": "class", "path": "mail_intake.auth.base.MailIntakeAuthProvider", - "signature": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials() -> T", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -519,60 +407,18 @@ "signature": null, "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.", "members": { - "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": "", + "signature": null, "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n **Responsibilities:**\n\n - Acquire credentials from an external provider.\n - Refresh or revalidate credentials as needed.\n - Handle authentication-specific failure modes.\n - Coordinate with credential persistence layers where applicable.\n\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n by the adapter.", "members": { "get_credentials": { "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials", - "signature": "", + "signature": "get_credentials()", "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\n Credentials of type `T` suitable for immediate use by the\n corresponding mail adapter.\n\nRaises:\n Exception:\n An authentication-specific exception indicating that\n credentials could not be obtained or validated.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception." } } @@ -581,28 +427,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.auth.google.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.auth.google.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -611,14 +457,14 @@ "name": "MailIntakeAuthError", "kind": "class", "path": "mail_intake.auth.google.MailIntakeAuthError", - "signature": "", + "signature": null, "docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials." }, "MailIntakeGoogleAuth": { "name": "MailIntakeGoogleAuth", "kind": "class", "path": "mail_intake.auth.google.MailIntakeGoogleAuth", - "signature": "", + "signature": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])", "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n **Responsibilities:**\n\n - Load cached credentials from a credential store when available.\n - Refresh expired credentials when possible.\n - Initiate an interactive OAuth flow only when required.\n - Persist refreshed or newly obtained credentials via the store.\n\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n internal state.", "members": { "credentials_path": { @@ -646,17 +492,10 @@ "name": "get_credentials", "kind": "function", "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials", - "signature": "", + "signature": "get_credentials() -> Any", "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use." } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.auth.google.Any", - "signature": "", - "docstring": null } } } @@ -673,28 +512,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -703,35 +542,35 @@ "name": "PickleCredentialStore", "kind": "class", "path": "mail_intake.credentials.PickleCredentialStore", - "signature": "", + "signature": "PickleCredentialStore(path: str)", "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n **Guarantees:**\n\n - Stores credentials on the local filesystem.\n - Uses `pickle` for serialization and deserialization.\n - Does not provide encryption, locking, or concurrency guarantees.\n\n **Constraints:**\n\n - Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.", "members": { "path": { "name": "path", "kind": "attribute", "path": "mail_intake.credentials.PickleCredentialStore.path", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.load", - "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "signature": "load()", + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials at the configured path are overwritten" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.PickleCredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n **Lifecycle:**\n\n - This method deletes the credential file if it exists and should be treated as an idempotent operation" } } @@ -740,63 +579,63 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.RedisCredentialStore", - "signature": "", + "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { "name": "redis", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.redis", - "signature": "", + "signature": null, "docstring": null }, "key": { "name": "key", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.key", - "signature": "", + "signature": null, "docstring": null }, "serialize": { "name": "serialize", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.serialize", - "signature": "", + "signature": null, "docstring": null }, "deserialize": { "name": "deserialize", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.deserialize", - "signature": "", + "signature": null, "docstring": null }, "ttl_seconds": { "name": "ttl_seconds", "kind": "attribute", "path": "mail_intake.credentials.RedisCredentialStore.ttl_seconds", - "signature": "", + "signature": null, "docstring": null }, "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "load()", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.RedisCredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } @@ -808,53 +647,32 @@ "signature": null, "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.", "members": { - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -870,7 +688,7 @@ "name": "PickleCredentialStore", "kind": "class", "path": "mail_intake.credentials.pickle.PickleCredentialStore", - "signature": "", + "signature": "PickleCredentialStore(path: str)", "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n **Guarantees:**\n\n - Stores credentials on the local filesystem.\n - Uses `pickle` for serialization and deserialization.\n - Does not provide encryption, locking, or concurrency guarantees.\n\n **Constraints:**\n\n - Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.", "members": { "path": { @@ -884,21 +702,21 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load", - "signature": "", - "docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." + "signature": "load() -> T | None", + "docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials at the configured path are overwritten" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n **Lifecycle:**\n\n - This method deletes the credential file if it exists and should be treated as an idempotent operation" } } @@ -912,53 +730,32 @@ "signature": null, "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.", "members": { - "Optional": { - "name": "Optional", - "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": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load()", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T)", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.CredentialStore.clear", - "signature": "", + "signature": "clear()", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -974,7 +771,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: int | None = None)", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -1016,31 +813,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", - "docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." + "signature": "load() -> T | None", + "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } }, @@ -1051,41 +841,6 @@ "signature": null, "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategiesβ€”such as local files, in-memory caches, distributed stores,\nor secrets managersβ€”without coupling authentication logic to any\nspecific storage mechanism.", "members": { - "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", @@ -1097,28 +852,28 @@ "name": "CredentialStore", "kind": "class", "path": "mail_intake.credentials.store.CredentialStore", - "signature": "", + "signature": null, "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.", "members": { "load": { "name": "load", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.load", - "signature": "", - "docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." + "signature": "load() -> T | None", + "docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.save", - "signature": "", + "signature": "save(credentials: T) -> None", "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.store.CredentialStore.clear", - "signature": "", + "signature": "clear() -> None", "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent" } } @@ -1138,22 +893,22 @@ "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.MailIntakeReader", - "signature": "", + "signature": "MailIntakeReader(adapter: MailIntakeAdapter)", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_messages", - "signature": "", + "signature": "iter_messages(query: str)", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads", - "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "signature": "iter_threads(query: str)", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } }, @@ -1164,132 +919,111 @@ "signature": null, "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.", "members": { - "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": "", + "signature": null, "docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", "members": { "iter_message_refs": { "name": "iter_message_refs", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" + "signature": "iter_message_refs(query: str)", + "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" }, "fetch_message": { "name": "fetch_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." + "signature": "fetch_message(message_id: str)", + "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." }, "fetch_thread": { "name": "fetch_thread", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." + "signature": "fetch_thread(thread_id: str)", + "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload." } } }, + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.ingestion.reader.MailIntakeParsingError", + "signature": null, + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, "MailIntakeMessage": { "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeMessage", - "signature": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "docstring": "Message timestamp as a timezone-naive UTC datetime." }, "from_email": { "name": "from_email", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_email", - "signature": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "docstring": "Short provider-supplied preview snippet of the message." }, "raw_headers": { "name": "raw_headers", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeMessage.raw_headers", - "signature": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -1298,108 +1032,101 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier." }, "normalized_subject": { "name": "normalized_subject", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.normalized_subject", - "signature": "", + "signature": null, "docstring": "Normalized subject line used to group related messages." }, "participants": { "name": "participants", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.participants", - "signature": "", + "signature": null, "docstring": "Set of unique participant email addresses observed in the thread." }, "messages": { "name": "messages", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.messages", - "signature": "", + "signature": null, "docstring": "Ordered list of messages belonging to this thread." }, "last_activity_at": { "name": "last_activity_at", "kind": "attribute", "path": "mail_intake.ingestion.reader.MailIntakeThread.last_activity_at", - "signature": "", + "signature": null, "docstring": "Timestamp of the most recent message in the thread." }, "add_message": { "name": "add_message", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage)", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } }, - "parse_headers": { - "name": "parse_headers", - "kind": "function", - "path": "mail_intake.ingestion.reader.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" - }, - "extract_sender": { - "name": "extract_sender", - "kind": "function", - "path": "mail_intake.ingestion.reader.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" - }, "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:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any])", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.ingestion.reader.extract_sender", + "signature": "extract_sender(headers: dict[str, str])", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + }, + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.ingestion.reader.parse_headers", + "signature": "parse_headers(raw_headers: list[dict[str, str]])", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "normalize_subject": { "name": "normalize_subject", "kind": "function", "path": "mail_intake.ingestion.reader.normalize_subject", - "signature": "", + "signature": "normalize_subject(subject: str)", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, - "MailIntakeParsingError": { - "name": "MailIntakeParsingError", - "kind": "class", - "path": "mail_intake.ingestion.reader.MailIntakeParsingError", - "signature": "", - "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, "MailIntakeReader": { "name": "MailIntakeReader", "kind": "class", "path": "mail_intake.ingestion.reader.MailIntakeReader", - "signature": "", + "signature": "MailIntakeReader(adapter: MailIntakeAdapter)", "docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.", "members": { "iter_messages": { "name": "iter_messages", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", - "signature": "", + "signature": "iter_messages(query: str) -> Iterator[MailIntakeMessage]", "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed." }, "iter_threads": { "name": "iter_threads", "kind": "function", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", - "signature": "", - "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." + "signature": "iter_threads(query: str) -> Iterator[MailIntakeThread]", + "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages." } } } @@ -1418,70 +1145,70 @@ "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.models.MailIntakeMessage", - "signature": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "docstring": "Message timestamp as a timezone-naive UTC datetime." }, "from_email": { "name": "from_email", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.from_email", - "signature": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "docstring": "Short provider-supplied preview snippet of the message." }, "raw_headers": { "name": "raw_headers", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.raw_headers", - "signature": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -1490,49 +1217,49 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier." }, "normalized_subject": { "name": "normalized_subject", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.normalized_subject", - "signature": "", + "signature": null, "docstring": "Normalized subject line used to group related messages." }, "participants": { "name": "participants", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.participants", - "signature": "", + "signature": null, "docstring": "Set of unique participant email addresses observed in the thread." }, "messages": { "name": "messages", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.messages", - "signature": "", + "signature": null, "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": "", + "signature": null, "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": "", + "signature": "add_message(message: MailIntakeMessage)", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } @@ -1544,39 +1271,11 @@ "signature": null, "docstring": "# Summary\n\nMessage 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { @@ -1653,109 +1352,74 @@ "signature": null, "docstring": "# Summary\n\nThread 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -1764,7 +1428,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -1806,17 +1470,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage) -> None", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } @@ -1833,28 +1490,28 @@ "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:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any])", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "signature": "parse_headers(raw_headers: list[dict[str, str]])", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + "signature": "extract_sender(headers: dict[str, str])", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "normalize_subject": { "name": "normalize_subject", "kind": "function", "path": "mail_intake.parsers.normalize_subject", - "signature": "", + "signature": "normalize_subject(subject: str)", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, "body": { @@ -1864,54 +1521,19 @@ "signature": null, "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", "members": { - "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": "", + "signature": null, "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." }, "extract_body": { "name": "extract_body", "kind": "function", "path": "mail_intake.parsers.body.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any]) -> str", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." } } }, @@ -1922,47 +1544,19 @@ "signature": null, "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", "members": { - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.headers.Dict", - "signature": "", - "docstring": null - }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.parsers.headers.List", - "signature": "", - "docstring": null - }, - "Tuple": { - "name": "Tuple", - "kind": "alias", - "path": "mail_intake.parsers.headers.Tuple", - "signature": "", - "docstring": null - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.headers.Optional", - "signature": "", - "docstring": null - }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "signature": "parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + "signature": "extract_sender(headers: dict[str, str]) -> tuple[str, str | None]", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } }, @@ -1973,18 +1567,11 @@ "signature": null, "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.", "members": { - "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": "", + "signature": "normalize_subject(subject: str) -> str", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/mcp_docs/modules/mail_intake.models.json b/docs/mcp/modules/mail_intake.models.json similarity index 70% rename from mcp_docs/modules/mail_intake.models.json rename to docs/mcp/modules/mail_intake.models.json index 9cf05a6..78fd77e 100644 --- a/mcp_docs/modules/mail_intake.models.json +++ b/docs/mcp/modules/mail_intake.models.json @@ -8,70 +8,70 @@ "name": "MailIntakeMessage", "kind": "class", "path": "mail_intake.models.MailIntakeMessage", - "signature": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "docstring": "Message timestamp as a timezone-naive UTC datetime." }, "from_email": { "name": "from_email", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.from_email", - "signature": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "docstring": "Short provider-supplied preview snippet of the message." }, "raw_headers": { "name": "raw_headers", "kind": "attribute", "path": "mail_intake.models.MailIntakeMessage.raw_headers", - "signature": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -80,49 +80,49 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier." }, "normalized_subject": { "name": "normalized_subject", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.normalized_subject", - "signature": "", + "signature": null, "docstring": "Normalized subject line used to group related messages." }, "participants": { "name": "participants", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.participants", - "signature": "", + "signature": null, "docstring": "Set of unique participant email addresses observed in the thread." }, "messages": { "name": "messages", "kind": "attribute", "path": "mail_intake.models.MailIntakeThread.messages", - "signature": "", + "signature": null, "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": "", + "signature": null, "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": "", + "signature": "add_message(message: MailIntakeMessage)", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } @@ -134,39 +134,11 @@ "signature": null, "docstring": "# Summary\n\nMessage 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { @@ -243,109 +215,74 @@ "signature": null, "docstring": "# Summary\n\nThread 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -354,7 +291,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -396,17 +333,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage) -> None", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } diff --git a/mcp_docs/modules/mail_intake.models.message.json b/docs/mcp/modules/mail_intake.models.message.json similarity index 76% rename from mcp_docs/modules/mail_intake.models.message.json rename to docs/mcp/modules/mail_intake.models.message.json index 52131ee..22f1ff8 100644 --- a/mcp_docs/modules/mail_intake.models.message.json +++ b/docs/mcp/modules/mail_intake.models.message.json @@ -4,39 +4,11 @@ "path": "mail_intake.models.message", "docstring": "# Summary\n\nMessage 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { diff --git a/mcp_docs/modules/mail_intake.models.thread.json b/docs/mcp/modules/mail_intake.models.thread.json similarity index 66% rename from mcp_docs/modules/mail_intake.models.thread.json rename to docs/mcp/modules/mail_intake.models.thread.json index aa60d60..c4aec2b 100644 --- a/mcp_docs/modules/mail_intake.models.thread.json +++ b/docs/mcp/modules/mail_intake.models.thread.json @@ -4,109 +4,74 @@ "path": "mail_intake.models.thread", "docstring": "# Summary\n\nThread 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": "", + "signature": "MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: str | None, subject: str, body_text: str, snippet: str, raw_headers: dict[str, str])", "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.", "members": { "message_id": { "name": "message_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.message_id", - "signature": "", + "signature": null, "docstring": "Provider-specific message identifier." }, "thread_id": { "name": "thread_id", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.thread_id", - "signature": "", + "signature": null, "docstring": "Provider-specific thread identifier to which this message belongs." }, "timestamp": { "name": "timestamp", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.timestamp", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Sender email address." }, "from_name": { "name": "from_name", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.from_name", - "signature": "", + "signature": null, "docstring": "Optional human-readable sender name." }, "subject": { "name": "subject", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.subject", - "signature": "", + "signature": null, "docstring": "Raw subject line of the message." }, "body_text": { "name": "body_text", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.body_text", - "signature": "", + "signature": null, "docstring": "Extracted plain-text body content of the message." }, "snippet": { "name": "snippet", "kind": "attribute", "path": "mail_intake.models.thread.MailIntakeMessage.snippet", - "signature": "", + "signature": null, "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": "", + "signature": null, "docstring": "Normalized mapping of message headers (header name β†’ value)." } } @@ -115,7 +80,7 @@ "name": "MailIntakeThread", "kind": "class", "path": "mail_intake.models.thread.MailIntakeThread", - "signature": "", + "signature": "MailIntakeThread(thread_id: str, normalized_subject: str, participants: set[str] = ..., messages: list[MailIntakeMessage] = ..., last_activity_at: datetime | None = ...)", "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.", "members": { "thread_id": { @@ -157,17 +122,10 @@ "name": "add_message", "kind": "function", "path": "mail_intake.models.thread.MailIntakeThread.add_message", - "signature": "", + "signature": "add_message(message: MailIntakeMessage) -> None", "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp." } } - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.models.thread.Optional", - "signature": "", - "docstring": null } } } diff --git a/docs/mcp/modules/mail_intake.parsers.body.json b/docs/mcp/modules/mail_intake.parsers.body.json new file mode 100644 index 0000000..a8cbcea --- /dev/null +++ b/docs/mcp/modules/mail_intake.parsers.body.json @@ -0,0 +1,23 @@ +{ + "module": "mail_intake.parsers.body", + "content": { + "path": "mail_intake.parsers.body", + "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", + "objects": { + "MailIntakeParsingError": { + "name": "MailIntakeParsingError", + "kind": "class", + "path": "mail_intake.parsers.body.MailIntakeParsingError", + "signature": null, + "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." + }, + "extract_body": { + "name": "extract_body", + "kind": "function", + "path": "mail_intake.parsers.body.extract_body", + "signature": "extract_body(payload: dict[str, Any]) -> str", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + } + } + } +} \ No newline at end of file diff --git a/docs/mcp/modules/mail_intake.parsers.headers.json b/docs/mcp/modules/mail_intake.parsers.headers.json new file mode 100644 index 0000000..1752e12 --- /dev/null +++ b/docs/mcp/modules/mail_intake.parsers.headers.json @@ -0,0 +1,23 @@ +{ + "module": "mail_intake.parsers.headers", + "content": { + "path": "mail_intake.parsers.headers", + "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", + "objects": { + "parse_headers": { + "name": "parse_headers", + "kind": "function", + "path": "mail_intake.parsers.headers.parse_headers", + "signature": "parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + }, + "extract_sender": { + "name": "extract_sender", + "kind": "function", + "path": "mail_intake.parsers.headers.extract_sender", + "signature": "extract_sender(headers: dict[str, str]) -> tuple[str, str | None]", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John 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/docs/mcp/modules/mail_intake.parsers.json similarity index 60% rename from mcp_docs/modules/mail_intake.parsers.json rename to docs/mcp/modules/mail_intake.parsers.json index 8c4c376..7d1e973 100644 --- a/mcp_docs/modules/mail_intake.parsers.json +++ b/docs/mcp/modules/mail_intake.parsers.json @@ -8,28 +8,28 @@ "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:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any])", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "signature": "parse_headers(raw_headers: list[dict[str, str]])", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + "signature": "extract_sender(headers: dict[str, str])", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" }, "normalize_subject": { "name": "normalize_subject", "kind": "function", "path": "mail_intake.parsers.normalize_subject", - "signature": "", + "signature": "normalize_subject(subject: str)", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." }, "body": { @@ -39,54 +39,19 @@ "signature": null, "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", "members": { - "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": "", + "signature": null, "docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." }, "extract_body": { "name": "extract_body", "kind": "function", "path": "mail_intake.parsers.body.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." + "signature": "extract_body(payload: dict[str, Any]) -> str", + "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." } } }, @@ -97,47 +62,19 @@ "signature": null, "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", "members": { - "Dict": { - "name": "Dict", - "kind": "alias", - "path": "mail_intake.parsers.headers.Dict", - "signature": "", - "docstring": null - }, - "List": { - "name": "List", - "kind": "alias", - "path": "mail_intake.parsers.headers.List", - "signature": "", - "docstring": null - }, - "Tuple": { - "name": "Tuple", - "kind": "alias", - "path": "mail_intake.parsers.headers.Tuple", - "signature": "", - "docstring": null - }, - "Optional": { - "name": "Optional", - "kind": "alias", - "path": "mail_intake.parsers.headers.Optional", - "signature": "", - "docstring": null - }, "parse_headers": { "name": "parse_headers", "kind": "function", "path": "mail_intake.parsers.headers.parse_headers", - "signature": "", - "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" + "signature": "parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]", + "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" }, "extract_sender": { "name": "extract_sender", "kind": "function", "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" + "signature": "extract_sender(headers: dict[str, str]) -> tuple[str, str | None]", + "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" } } }, @@ -148,18 +85,11 @@ "signature": null, "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.", "members": { - "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": "", + "signature": "normalize_subject(subject: str) -> str", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/mcp_docs/modules/mail_intake.parsers.subject.json b/docs/mcp/modules/mail_intake.parsers.subject.json similarity index 80% rename from mcp_docs/modules/mail_intake.parsers.subject.json rename to docs/mcp/modules/mail_intake.parsers.subject.json index 14c4cc7..7b678fd 100644 --- a/mcp_docs/modules/mail_intake.parsers.subject.json +++ b/docs/mcp/modules/mail_intake.parsers.subject.json @@ -4,18 +4,11 @@ "path": "mail_intake.parsers.subject", "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.", "objects": { - "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": "", + "signature": "normalize_subject(subject: str) -> str", "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject." } } diff --git a/docs/mcp/nav.json b/docs/mcp/nav.json new file mode 100644 index 0000000..fe9270b --- /dev/null +++ b/docs/mcp/nav.json @@ -0,0 +1,90 @@ +[ + { + "module": "mail_intake", + "resource": "docs://modules/mail_intake" + }, + { + "module": "mail_intake.adapters", + "resource": "docs://modules/mail_intake.adapters" + }, + { + "module": "mail_intake.adapters.base", + "resource": "docs://modules/mail_intake.adapters.base" + }, + { + "module": "mail_intake.adapters.gmail", + "resource": "docs://modules/mail_intake.adapters.gmail" + }, + { + "module": "mail_intake.auth", + "resource": "docs://modules/mail_intake.auth" + }, + { + "module": "mail_intake.auth.base", + "resource": "docs://modules/mail_intake.auth.base" + }, + { + "module": "mail_intake.auth.google", + "resource": "docs://modules/mail_intake.auth.google" + }, + { + "module": "mail_intake.config", + "resource": "docs://modules/mail_intake.config" + }, + { + "module": "mail_intake.credentials", + "resource": "docs://modules/mail_intake.credentials" + }, + { + "module": "mail_intake.credentials.pickle", + "resource": "docs://modules/mail_intake.credentials.pickle" + }, + { + "module": "mail_intake.credentials.redis", + "resource": "docs://modules/mail_intake.credentials.redis" + }, + { + "module": "mail_intake.credentials.store", + "resource": "docs://modules/mail_intake.credentials.store" + }, + { + "module": "mail_intake.exceptions", + "resource": "docs://modules/mail_intake.exceptions" + }, + { + "module": "mail_intake.ingestion", + "resource": "docs://modules/mail_intake.ingestion" + }, + { + "module": "mail_intake.ingestion.reader", + "resource": "docs://modules/mail_intake.ingestion.reader" + }, + { + "module": "mail_intake.models", + "resource": "docs://modules/mail_intake.models" + }, + { + "module": "mail_intake.models.message", + "resource": "docs://modules/mail_intake.models.message" + }, + { + "module": "mail_intake.models.thread", + "resource": "docs://modules/mail_intake.models.thread" + }, + { + "module": "mail_intake.parsers", + "resource": "docs://modules/mail_intake.parsers" + }, + { + "module": "mail_intake.parsers.body", + "resource": "docs://modules/mail_intake.parsers.body" + }, + { + "module": "mail_intake.parsers.headers", + "resource": "docs://modules/mail_intake.parsers.headers" + }, + { + "module": "mail_intake.parsers.subject", + "resource": "docs://modules/mail_intake.parsers.subject" + } +] \ No newline at end of file diff --git a/mkdocs.yml b/docs/mkdocs.lib.yml similarity index 91% rename from mkdocs.yml rename to docs/mkdocs.lib.yml index 36e786f..78810df 100644 --- a/mkdocs.yml +++ b/docs/mkdocs.lib.yml @@ -21,33 +21,15 @@ theme: - search.highlight - search.share - search.suggest -plugins: -- search -- mkdocstrings: - handlers: - python: - paths: - - . - options: - docstring_style: google - show_source: false - show_signature_annotations: true - separate_signature: true - merge_init_into_class: true - inherited_members: true - annotations_path: brief - show_root_heading: true - group_by_category: true - show_category_heading: true - show_object_full_path: false - show_symbol_type_heading: true + icon: + logo: material/inbox + repo: fontawesome/brands/github markdown_extensions: - pymdownx.superfences - pymdownx.inlinehilite - pymdownx.snippets - admonition - pymdownx.details -- pymdownx.superfences - pymdownx.highlight: linenums: true anchor_linenums: true @@ -62,7 +44,31 @@ markdown_extensions: - pymdownx.caret - pymdownx.tilde - pymdownx.mark +extra_css: +- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css +plugins: +- search +- mkdocstrings: + handlers: + python: + paths: + - .. + options: + docstring_style: google + show_source: false + show_signature_annotations: true + separate_signature: true + merge_init_into_class: true + inherited_members: true + annotations_path: brief + show_root_heading: true + group_by_category: true + show_category_heading: true + show_object_full_path: false + show_symbol_type_heading: true site_name: mail_intake +docs_dir: lib +site_dir: ../site/lib nav: - Home: index.md - Core API: diff --git a/docs/mkdocs.wiki.yml b/docs/mkdocs.wiki.yml new file mode 100644 index 0000000..252c263 --- /dev/null +++ b/docs/mkdocs.wiki.yml @@ -0,0 +1,69 @@ +site_name: Mail Intake Documentation +docs_dir: wiki +site_dir: ../site/wiki + +nav: +- Home: index.md +- Overview: 01_overview.md +- How to Use: 02_how_to_use.md +- Extending Mail Intake: 03_extending.md +- Development: 04_development.md + +theme: + name: material + palette: + scheme: slate + primary: blue grey + accent: teal + font: + text: Roboto + code: JetBrains Mono + features: + - navigation.sections + - navigation.expand + - navigation.top + - navigation.instant + - navigation.tracking + - navigation.indexes + - content.code.copy + - content.code.annotate + - content.tabs.link + - content.action.edit + - search.highlight + - search.share + - search.suggest + - navigation.tabs + - toc.integrate + - header.autohide + - announce.dismiss + - footer.social + - content.code.select + - content.code.line_numbers + - content.tooltips + icon: + logo: material/inbox + repo: fontawesome/brands/github +markdown_extensions: +- pymdownx.superfences +- pymdownx.inlinehilite +- pymdownx.snippets +- admonition +- pymdownx.details +- pymdownx.highlight: + linenums: true + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.tabbed: + alternate_style: true +- pymdownx.tasklist: + custom_checkbox: true +- tables +- footnotes +- pymdownx.caret +- pymdownx.tilde +- pymdownx.mark +extra_css: +- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css +plugins: +- search \ No newline at end of file diff --git a/docs/wiki/01_overview.md b/docs/wiki/01_overview.md new file mode 100644 index 0000000..43c3f27 --- /dev/null +++ b/docs/wiki/01_overview.md @@ -0,0 +1,91 @@ +# 🧱 Overview + +Mail Intake is a **contract-first ingestion pipeline**. Adapters handle +transport to a provider, parsers normalize provider payloads, and the reader +orchestrates the whole flow into canonical domain models. + +--- + +## πŸ—οΈ Architecture + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ External Provider (e.g. Gmail API) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ MailIntakeAdapter (transport) β”‚ provider API calls + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ provider-native payloads + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Parsers (normalization) β”‚ headers, body, subject + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ composed + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ MailIntakeReader (orchestration) β”‚ iter_messages / iter_threads + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ MailIntakeMessage / Thread β”‚ canonical domain models + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +Layers: + +1. **Adapters** (`mail_intake.adapters`) β€” provider-specific, read-only + transport. Return provider-native payloads; never interpret them. +2. **Auth** (`mail_intake.auth`) β€” credential acquisition and lifecycle + management, decoupled from adapters. +3. **Credentials** (`mail_intake.credentials`) β€” persistence of auth tokens; + `PickleCredentialStore` locally, `RedisCredentialStore` for production. +4. **Parsers** (`mail_intake.parsers`) β€” extract headers, body text, sender, + and normalized subjects from provider payloads. +5. **Ingestion** (`mail_intake.ingestion`) β€” `MailIntakeReader` wires an + adapter + parsers into iterators over canonical models. +6. **Models** (`mail_intake.models`) β€” provider-agnostic `MailIntakeMessage` + and `MailIntakeThread`. + +--- + +## πŸ“¦ Domain models + +`MailIntakeMessage`: + +| Field | Type | Meaning | +|---|---|---| +| `message_id` | `str` | Provider message id | +| `thread_id` | `str` | Conversation thread id | +| `timestamp` | `datetime` | Message timestamp | +| `from_email` | `str` | Sender email | +| `from_name` | `str \| None` | Sender display name | +| `subject` | `str` | Message subject | +| `body_text` | `str` | Extracted plain-text body | +| `snippet` | `str` | Provider snippet | +| `raw_headers` | `dict[str, str]` | Unmodified headers | + +`MailIntakeThread`: + +| Field | Type | Meaning | +|---|---|---| +| `thread_id` | `str` | Conversation id | +| `normalized_subject` | `str` | Normalized subject (threads share one) | +| `participants` | `set[str]` | Distinct senders | +| `messages` | `list[MailIntakeMessage]` | Ordered messages | +| `last_activity_at` | `datetime \| None` | Latest message time | + +--- + +## πŸ”’ Design guarantees + +- Read-only access β€” no mutation of provider state. +- Provider-agnostic domain models. +- Explicit configuration and dependency injection (no implicit env reads). +- Extensible via public contracts; built-in adapters are reference + implementations and may change internally. + +--- + +## πŸ“š Read Next + +- [How to Use](02_how_to_use.md) β€” the Gmail ingestion flow. +- [Extending Mail Intake](03_extending.md) β€” custom adapters and stores. \ No newline at end of file diff --git a/docs/wiki/02_how_to_use.md b/docs/wiki/02_how_to_use.md new file mode 100644 index 0000000..41f8e20 --- /dev/null +++ b/docs/wiki/02_how_to_use.md @@ -0,0 +1,105 @@ +# πŸ–₯️ How to Use + +This page walks through authenticating, ingesting, and parsing mail with the +built-in Gmail support. + +--- + +## πŸ” Authentication + +Create a credential store and an auth provider: + +```python +from mail_intake.auth import MailIntakeGoogleAuth +from mail_intake.credentials import PickleCredentialStore, RedisCredentialStore + +store = PickleCredentialStore(path="token.pickle") # local dev + +auth = MailIntakeGoogleAuth( + credentials_path="credentials.json", # your OAuth client file + store=store, + scopes=["https://www.googleapis.com/auth/gmail.readonly"], +) +``` + +> OAuth credentials come from the Google Cloud Console and are provided via +> file paths β€” never hard-code tokens or secrets in source. Once authorized, +> the token is persisted by the credential store and refreshed automatically. + +For distributed deployments, use Redis instead of pickle: + +```python +store = RedisCredentialStore(redis_client=redis_client) # production +``` + +--- + +## πŸ“₯ Ingesting messages + +Build an adapter and a reader, then iterate: + +```python +from mail_intake.ingestion import MailIntakeReader +from mail_intake.adapters import MailIntakeGmailAdapter + +adapter = MailIntakeGmailAdapter(auth_provider=auth) +reader = MailIntakeReader(adapter) + +for message in reader.iter_messages("from:recruiter@example.com"): + print(message.subject, message.from_email, message.timestamp) +``` + +Access the full model: + +```python +message.message_id # provider id +message.thread_id +message.body_text # plain-text body +message.raw_headers # unmodified headers dict +``` + +--- + +## πŸ”– Ingesting threads + +```python +for thread in reader.iter_threads("subject:Interview"): + print(thread.normalized_subject) + print(thread.participants) + print(len(thread.messages)) + print(thread.last_activity_at) +``` + +`MailIntakeThread` aggregates its messages, participants, and last activity. + +--- + +## πŸ§ͺ Parsers + +Parsers normalize provider payloads and are used by the reader internally. +They are also importable on their own: + +```python +from mail_intake.parsers import extract_body, parse_headers, normalize_subject +``` + +- `extract_body(...)` β€” plain-text body extraction. +- `parse_headers(...)` β€” structured header parsing. +- `extract_sender(...)` β€” sender email/name extraction. +- `normalize_subject(...)` β€” subject normalization for threading. + +--- + +## βœ… Checklist + +1. Provide OAuth credentials via a file path and a credential store. +2. Build the `MailIntakeGoogleAuth` provider with the Gmail read-only scope. +3. Wrap the adapter in a `MailIntakeReader`. +4. Consume `iter_messages` / `iter_threads`; never call provider APIs directly. + +--- + +## πŸ“š Read Next + +- [Overview](01_overview.md) β€” layers and domain models. +- [Extending Mail Intake](03_extending.md) β€” custom providers and stores. \ No newline at end of file diff --git a/docs/wiki/03_extending.md b/docs/wiki/03_extending.md new file mode 100644 index 0000000..e9bf6e6 --- /dev/null +++ b/docs/wiki/03_extending.md @@ -0,0 +1,106 @@ +# 🧩 Extending Mail Intake + +Mail Intake is designed to be extended through its **public contracts**. +Implement your own adapter, auth provider, or credential store to support a +new provider or storage backend. + +--- + +## πŸ“¬ Custom adapters + +Subclass `MailIntakeAdapter` to integrate a new provider. Adapters perform +read-only transport and return provider-native payloads: + +```python +from mail_intake.adapters import MailIntakeAdapter + +class ExchangeAdapter(MailIntakeAdapter): + def __init__(self, auth_provider): + self._auth = auth_provider + + def fetch_messages(self, query): + # call the provider API, return native payloads + ... + + def fetch_threads(self, query): + ... +``` + +> **Do not** subclass built-in adapters like `MailIntakeGmailAdapter` β€” they +> are reference implementations and may change internally without notice. + +--- + +## πŸ” Custom auth providers + +Subclass `MailIntakeAuthProvider[T]` to own a different credential flow: + +```python +from mail_intake.auth import MailIntakeAuthProvider + +class ExchangeAuth(MailIntakeAuthProvider[exchange_credentials]): + def get_credentials(self): + return self._store.load() + + def refresh(self): + ... +``` + +Auth providers remain decoupled from adapter logic β€” they only manage +credentials. + +--- + +## πŸ—„οΈ Custom credential stores + +Implement the `CredentialStore[T]` contract for a new persistence backend: + +```python +from mail_intake.credentials import CredentialStore + +class S3CredentialStore(CredentialStore): + def save(self, credentials): + ... + + def load(self): + ... + + def delete(self): + ... +``` + +The store abstraction keeps tokens out of config and rotates safely. + +--- + +## πŸ§ͺ Wiring a custom backend + +```python +from mail_intake.ingestion import MailIntakeReader + +auth = ExchangeAuth(store=S3CredentialStore(...)) +adapter = ExchangeAdapter(auth_provider=auth) +reader = MailIntakeReader(adapter) + +for message in reader.iter_messages("query"): + print(message.subject) +``` + +The reader only depends on the adapter contract, so the rest of the pipeline +keeps working unchanged. + +--- + +## βœ… Extension checklist + +1. Implement the **public contract** β€” never subclass built-in adapters. +2. Keep transport in the adapter, parsing in parsers, auth in the provider. +3. Return the provider-native payload and let parsers normalize it. +4. Inject dependencies explicitly β€” no global state or env reads. + +--- + +## πŸ“š Read Next + +- [How to Use](02_how_to_use.md) β€” the built-in Gmail flow. +- [Development](04_development.md) β€” running tests and docs. \ No newline at end of file diff --git a/docs/wiki/04_development.md b/docs/wiki/04_development.md new file mode 100644 index 0000000..b55c933 --- /dev/null +++ b/docs/wiki/04_development.md @@ -0,0 +1,88 @@ +# πŸ› οΈ Development + +Working on `mail-intake` itself. + +--- + +## πŸ“‚ Repository layout + +| Path | Purpose | +|---|---| +| `mail_intake/` | The library package (adapters, auth, credentials, parsers, ingestion, models) | +| `mail_intake/*.pyi` | Type stubs kept in sync with implementations | +| `tests/` | Unit and integration tests (mock transports, no live mail) | +| `docs/lib/` | Generated library reference (docforge, flat layout) | +| `docs/mcp/` | Machine-readable bundle served by the MCP server | +| `docs/wiki/` | This hand-written wiki | + +--- + +## πŸ”§ Setup + +```bash +python -m venv .venv +.venv/Scripts/pip install -e ".[dev]" +``` + +> OAuth credential files (`credentials*.json`, `token.pickle`, +> `client_secret_*.json`) are gitignored β€” keep them out of the repository. + +--- + +## πŸ§ͺ Tests + +Run the suite (no network or live Gmail required): + +```bash +.venv/Scripts/pytest +``` + +Coverage spans ingestion flows, credential stores, parsers, and auth against +mock providers. + +--- + +## βœ… Quality gates + +The CI quality gate runs, matching the Drone pipeline: + +```bash +.venv/Scripts/black --check . +.venv/Scripts/ruff check . +.venv/Scripts/mypy +.venv/Scripts/pytest +``` + +--- + +## πŸ“ Building documentation (docforge) + +The site is generated by [`docforge`](https://git.aetoskia.com/aetos/doc-forge) +and served per kind under `site/{kind}`: + +```bash +doc-forge build \ + --mkdocs --mcp --wiki \ + --module-is-source --module mail_intake \ + --site-name "Mail Intake" +``` + +- `--module-is-source` renders the flat `docs/lib/` layout (no nesting under + `mail_intake/`), matching `docforge.nav.yml` and `docs/mkdocs.lib.yml`. +- `--mcp` regenerates the structured bundle in `docs/mcp/`. +- `--wiki` builds this wiki. + +Preview locally: + +```bash +doc-forge serve --lib +doc-forge serve --wiki +doc-forge serve --mcp +``` + +--- + +## πŸ“š Read Next + +- [Extending Mail Intake](03_extending.md) β€” custom adapters and stores. +- [Overview](01_overview.md) β€” the core architecture. \ No newline at end of file diff --git a/docs/wiki/index.md b/docs/wiki/index.md new file mode 100644 index 0000000..27c3a64 --- /dev/null +++ b/docs/wiki/index.md @@ -0,0 +1,71 @@ +# πŸ“¬ Mail Intake β€” Provider-Agnostic Email Ingestion + +`Mail Intake` is a contract-first, read-only email ingestion framework. It +pulls mail from external providers (such as Gmail), parses and normalizes it +into clean, provider-agnostic domain models β€” ready to persist, index, or +analyze downstream. + +> **Doc model:** this wiki is written for humans β€” how‑to guides and extension +> recipes. The authoritative API contracts live in the code (GSDFC docstrings) +> and the machine‑readable bundle under `docs/mcp/`. + +--- + +## πŸš€ Key Features + +* πŸ“¬ **Read-only ingestion** β€” never mutates provider state +* 🧩 **Contract-first layers** β€” adapters, parsers, and readers separated +* βœ‰οΈ **Provider-agnostic models** β€” `MailIntakeMessage` / `MailIntakeThread` + have no provider internals +* πŸ” **Extensible auth** β€” pluggable auth providers and credential stores + (pickle for dev, Redis for production) +* πŸ§ͺ **Deterministic & testable** β€” no implicit global state or env reads +* πŸ“Š **Gmail support** β€” reference adapter built on the official Google APIs + +--- + +## ⚑ Quick Start + +```python +from mail_intake.ingestion import MailIntakeReader +from mail_intake.adapters import MailIntakeGmailAdapter +from mail_intake.auth import MailIntakeGoogleAuth +from mail_intake.credentials import PickleCredentialStore + +store = PickleCredentialStore(path="token.pickle") + +auth = MailIntakeGoogleAuth( + credentials_path="credentials.json", + store=store, + scopes=["https://www.googleapis.com/auth/gmail.readonly"], +) + +adapter = MailIntakeGmailAdapter(auth_provider=auth) +reader = MailIntakeReader(adapter) + +for message in reader.iter_messages("from:recruiter@example.com"): + print(message.subject, message.from_email) +``` + +--- + +## πŸ“ Documentation Structure + +| Section | What you'll find | +|---|---| +| [Overview](01_overview.md) | Layers, domain models, and design guarantees | +| [How to Use](02_how_to_use.md) | Gmail ingestion, parsing, and credential stores | +| [Extending Mail Intake](03_extending.md) | Custom adapters, auth providers, stores | +| [Development](04_development.md) | Setup, tests, and regenerating docs | + +--- + +## πŸ”— Related Resources + +* **Source Code:** [Gitea Repository](https://git.aetoskia.com/aetos/mail-intake) +* **Internal PyPI:** [pip.aetoskia.com/simple/mail-intake](https://pip.aetoskia.com/simple/mail-intake) +* **CI:** Builds and publishes tagged releases, gated on black / ruff / mypy / pytest. + +--- + +Β© Aetoskia Internal β€” `mail-intake` 0.0.2 \ No newline at end of file diff --git a/mail_intake/__init__.py b/mail_intake/__init__.py index ea5585b..4fd02c7 100644 --- a/mail_intake/__init__.py +++ b/mail_intake/__init__.py @@ -137,7 +137,6 @@ No individual symbols are re-exported at the package root. --- """ - from . import ingestion from . import adapters from . import auth diff --git a/mail_intake/__init__.pyi b/mail_intake/__init__.pyi index dcf3ed8..a6d296c 100644 --- a/mail_intake/__init__.pyi +++ b/mail_intake/__init__.pyi @@ -1,10 +1,4 @@ -from . import ingestion -from . import adapters -from . import auth -from . import credentials -from . import models -from . import config -from . import exceptions +from . import adapters, auth, config, credentials, exceptions, ingestion, models __all__ = [ "ingestion", diff --git a/mail_intake/adapters/base.py b/mail_intake/adapters/base.py index eadaa77..1dd52cf 100644 --- a/mail_intake/adapters/base.py +++ b/mail_intake/adapters/base.py @@ -12,7 +12,8 @@ types or semantics should leak beyond implementations of this interface. """ from abc import ABC, abstractmethod -from typing import Iterator, Dict, Any +from collections.abc import Iterator +from typing import Any class MailIntakeAdapter(ABC): @@ -32,7 +33,7 @@ class MailIntakeAdapter(ABC): """ @abstractmethod - def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: + def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: """ Iterate over lightweight message references matching a query. @@ -40,8 +41,12 @@ class MailIntakeAdapter(ABC): query (str): Provider-specific query string used to filter messages. + Returns: + Iterator[dict[str, str]]: + An iterator over lightweight message reference dictionaries. + Yields: - Dict[str, str]: + dict[str, str]: Dictionaries containing message and thread identifiers. Notes: @@ -63,7 +68,7 @@ class MailIntakeAdapter(ABC): raise NotImplementedError @abstractmethod - def fetch_message(self, message_id: str) -> Dict[str, Any]: + def fetch_message(self, message_id: str) -> dict[str, Any]: """ Fetch a full raw message by message identifier. @@ -72,13 +77,13 @@ class MailIntakeAdapter(ABC): Provider-specific message identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure). """ raise NotImplementedError @abstractmethod - def fetch_thread(self, thread_id: str) -> Dict[str, Any]: + def fetch_thread(self, thread_id: str) -> dict[str, Any]: """ Fetch a full raw thread by thread identifier. @@ -87,7 +92,7 @@ class MailIntakeAdapter(ABC): Provider-specific thread identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native thread payload. """ raise NotImplementedError diff --git a/mail_intake/adapters/base.pyi b/mail_intake/adapters/base.pyi index 8cdcbd7..076a24c 100644 --- a/mail_intake/adapters/base.pyi +++ b/mail_intake/adapters/base.pyi @@ -1,10 +1,11 @@ from abc import ABC, abstractmethod -from typing import Iterator, Dict, Any +from collections.abc import Iterator +from typing import Any class MailIntakeAdapter(ABC): @abstractmethod - def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ... + def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ... @abstractmethod - def fetch_message(self, message_id: str) -> Dict[str, Any]: ... + def fetch_message(self, message_id: str) -> dict[str, Any]: ... @abstractmethod - def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ... + def fetch_thread(self, thread_id: str) -> dict[str, Any]: ... diff --git a/mail_intake/adapters/gmail.py b/mail_intake/adapters/gmail.py index 49ecd64..131cf62 100644 --- a/mail_intake/adapters/gmail.py +++ b/mail_intake/adapters/gmail.py @@ -15,14 +15,15 @@ It is the only place in the codebase where: All Gmail-specific behavior must be strictly contained within this module. """ -from typing import Iterator, Dict, Any +from collections.abc import Iterator +from typing import Any from googleapiclient.discovery import build from googleapiclient.errors import HttpError from mail_intake.adapters.base import MailIntakeAdapter -from mail_intake.exceptions import MailIntakeAdapterError from mail_intake.auth.base import MailIntakeAuthProvider +from mail_intake.exceptions import MailIntakeAdapterError class MailIntakeGmailAdapter(MailIntakeAdapter): @@ -71,10 +72,6 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): """ Lazily initialize and return the Gmail API service client. - Returns: - Any: - Initialized Gmail API service instance. - Raises: MailIntakeAdapterError: If the Gmail service cannot be initialized. @@ -89,7 +86,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): ) from exc return self._service - def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: + def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: """ Iterate over message references matching the query. @@ -98,7 +95,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail search query string. Yields: - Dict[str, str]: + dict[str, str]: Dictionaries containing ``message_id`` and ``thread_id``. Raises: @@ -107,9 +104,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): """ try: request = ( - self.service.users() - .messages() - .list(userId=self._user_id, q=query) + self.service.users().messages().list(userId=self._user_id, q=query) ) while request is not None: @@ -121,18 +116,14 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): "thread_id": msg["threadId"], } - request = ( - self.service.users() - .messages() - .list_next(request, response) - ) + request = self.service.users().messages().list_next(request, response) except HttpError as exc: raise MailIntakeAdapterError( "Gmail API error while listing messages" ) from exc - def fetch_message(self, message_id: str) -> Dict[str, Any]: + def fetch_message(self, message_id: str) -> dict[str, Any]: """ Fetch a full Gmail message by message ID. @@ -141,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail message identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native Gmail message payload. Raises: @@ -160,7 +151,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): f"Gmail API error while fetching message {message_id}" ) from exc - def fetch_thread(self, thread_id: str) -> Dict[str, Any]: + def fetch_thread(self, thread_id: str) -> dict[str, Any]: """ Fetch a full Gmail thread by thread ID. @@ -169,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter): Gmail thread identifier. Returns: - Dict[str, Any]: + dict[str, Any]: Provider-native Gmail thread payload. Raises: diff --git a/mail_intake/adapters/gmail.pyi b/mail_intake/adapters/gmail.pyi index 04204e7..7c88877 100644 --- a/mail_intake/adapters/gmail.pyi +++ b/mail_intake/adapters/gmail.pyi @@ -1,11 +1,15 @@ -from typing import Iterator, Dict, Any +from collections.abc import Iterator +from typing import 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: ... + def __init__( + self, auth_provider: MailIntakeAuthProvider[Any], user_id: str = ... + ) -> None: ... @property def service(self) -> Any: ... - def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ... - def fetch_message(self, message_id: str) -> Dict[str, Any]: ... - def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ... + def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ... + def fetch_message(self, message_id: str) -> dict[str, Any]: ... + def fetch_thread(self, thread_id: str) -> dict[str, Any]: ... diff --git a/mail_intake/auth/google.py b/mail_intake/auth/google.py index afc46dd..2787f4f 100644 --- a/mail_intake/auth/google.py +++ b/mail_intake/auth/google.py @@ -17,12 +17,12 @@ No Google authentication details should leak outside this module. """ import os -from typing import Sequence +from collections.abc import Sequence import google.auth.exceptions from google.auth.transport.requests import Request -from google_auth_oauthlib.flow import InstalledAppFlow from google.oauth2.credentials import Credentials +from google_auth_oauthlib.flow import InstalledAppFlow from mail_intake.auth.base import MailIntakeAuthProvider from mail_intake.credentials.store import CredentialStore diff --git a/mail_intake/auth/google.pyi b/mail_intake/auth/google.pyi index 57f16df..8b9d1ab 100644 --- a/mail_intake/auth/google.pyi +++ b/mail_intake/auth/google.pyi @@ -1,7 +1,11 @@ -from typing import Sequence, Any +from collections.abc import Sequence +from typing import Any + from mail_intake.auth.base import MailIntakeAuthProvider from mail_intake.credentials.store import CredentialStore class MailIntakeGoogleAuth(MailIntakeAuthProvider[Any]): - def __init__(self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str]) -> None: ... + def __init__( + self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str] + ) -> None: ... def get_credentials(self) -> Any: ... diff --git a/mail_intake/config.py b/mail_intake/config.py index e518218..f143cbd 100644 --- a/mail_intake/config.py +++ b/mail_intake/config.py @@ -12,7 +12,6 @@ environment reads to ensure predictability and testability. """ from dataclasses import dataclass -from typing import Optional @dataclass(frozen=True) @@ -46,12 +45,12 @@ class MailIntakeConfig: Whether ingestion should operate in read-only mode. """ - credentials_path: Optional[str] = None + credentials_path: str | None = None """ Optional path to provider credentials configuration. """ - token_path: Optional[str] = None + token_path: str | None = None """ Optional path to persisted authentication tokens. """ diff --git a/mail_intake/config.pyi b/mail_intake/config.pyi index a484b2c..827bfb4 100644 --- a/mail_intake/config.pyi +++ b/mail_intake/config.pyi @@ -1,9 +1,14 @@ -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: ... + credentials_path: str | None + token_path: str | None + def __init__( + self, + provider: str = ..., + user_id: str = ..., + readonly: bool = ..., + credentials_path: str | None = ..., + token_path: str | None = ..., + ) -> None: ... diff --git a/mail_intake/credentials/__init__.pyi b/mail_intake/credentials/__init__.pyi index 67256d1..862a4e3 100644 --- a/mail_intake/credentials/__init__.pyi +++ b/mail_intake/credentials/__init__.pyi @@ -1,5 +1,5 @@ -from .store import CredentialStore from .pickle import PickleCredentialStore from .redis import RedisCredentialStore +from .store import CredentialStore __all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"] diff --git a/mail_intake/credentials/pickle.py b/mail_intake/credentials/pickle.py index 472d8c1..0021722 100644 --- a/mail_intake/credentials/pickle.py +++ b/mail_intake/credentials/pickle.py @@ -16,7 +16,7 @@ untrusted environments. """ import pickle -from typing import Optional, TypeVar +from typing import TypeVar from mail_intake.credentials.store import CredentialStore @@ -55,12 +55,12 @@ class PickleCredentialStore(CredentialStore[T]): """ self.path = path - def load(self) -> Optional[T]: + def load(self) -> T | None: """ Load credentials from the local filesystem. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are present and successfully deserialized; otherwise `None`. diff --git a/mail_intake/credentials/pickle.pyi b/mail_intake/credentials/pickle.pyi index ea6fa5c..3f38f36 100644 --- a/mail_intake/credentials/pickle.pyi +++ b/mail_intake/credentials/pickle.pyi @@ -1,4 +1,5 @@ -from typing import Optional, TypeVar +from typing import TypeVar + from .store import CredentialStore T = TypeVar("T") @@ -6,6 +7,6 @@ T = TypeVar("T") class PickleCredentialStore(CredentialStore[T]): path: str def __init__(self, path: str) -> None: ... - def load(self) -> Optional[T]: ... + def load(self) -> T | None: ... def save(self, credentials: T) -> None: ... def clear(self) -> None: ... diff --git a/mail_intake/credentials/redis.py b/mail_intake/credentials/redis.py index 6db57ef..9d64fe2 100644 --- a/mail_intake/credentials/redis.py +++ b/mail_intake/credentials/redis.py @@ -24,8 +24,8 @@ Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations. """ - -from typing import Optional, TypeVar, Callable +from collections.abc import Callable +from typing import Any, TypeVar from mail_intake.credentials.store import CredentialStore @@ -57,30 +57,27 @@ class RedisCredentialStore(CredentialStore[T]): def __init__( self, - redis_client, + redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], - ttl_seconds: Optional[int] = None, + ttl_seconds: int | None = None, ): """ Initialize a Redis-backed credential store. Args: redis_client (Any): - An initialized Redis client instance (for example, ``redis.Redis`` or a compatible interface) used to communicate with the Redis server. - + Initialized Redis client instance used for persistence. key (str): - The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions. - + Storage key under which credentials are persisted. serialize (Callable[[T], bytes]): - A callable that converts a credential object of type ``T`` into a ``bytes`` representation suitable for storage in Redis. - + Callable that encodes credentials to bytes for storage. deserialize (Callable[[bytes], T]): - A callable that converts a ``bytes`` payload retrieved from Redis back into a credential object of type ``T``. - - ttl_seconds (Optional[int]): - Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If ``None``, credentials are stored without an expiration. + Callable that decodes stored bytes back into credentials. + ttl_seconds (int | None): + Optional time-to-live in seconds after which stored + credentials expire automatically. ``None`` disables expiry. """ self.redis = redis_client self.key = key @@ -88,12 +85,12 @@ class RedisCredentialStore(CredentialStore[T]): self.deserialize = deserialize self.ttl_seconds = ttl_seconds - def load(self) -> Optional[T]: + def load(self) -> T | None: """ Load credentials from Redis. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are present and successfully deserialized; otherwise `None`. diff --git a/mail_intake/credentials/redis.pyi b/mail_intake/credentials/redis.pyi index 52dcdf0..63ba4e6 100644 --- a/mail_intake/credentials/redis.pyi +++ b/mail_intake/credentials/redis.pyi @@ -1,4 +1,6 @@ -from typing import Optional, TypeVar, Callable, Any +from collections.abc import Callable +from typing import Any, TypeVar + from .store import CredentialStore T = TypeVar("T") @@ -8,8 +10,15 @@ class RedisCredentialStore(CredentialStore[T]): 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]: ... + ttl_seconds: int | None + def __init__( + self, + redis_client: Any, + key: str, + serialize: Callable[[T], bytes], + deserialize: Callable[[bytes], T], + ttl_seconds: int | None = ..., + ) -> None: ... + def load(self) -> T | None: ... 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 53899ef..5ca720b 100644 --- a/mail_intake/credentials/store.py +++ b/mail_intake/credentials/store.py @@ -19,9 +19,8 @@ or secrets managersβ€”without coupling authentication logic to any specific storage mechanism. """ - from abc import ABC, abstractmethod -from typing import Generic, Optional, TypeVar +from typing import Generic, TypeVar T = TypeVar("T") @@ -48,12 +47,12 @@ class CredentialStore(ABC, Generic[T]): """ @abstractmethod - def load(self) -> Optional[T]: + def load(self) -> T | None: """ Load previously persisted credentials. Returns: - Optional[T]: + T | None: An instance of type `T` if credentials are available and loadable; otherwise `None`. diff --git a/mail_intake/credentials/store.pyi b/mail_intake/credentials/store.pyi index 4798ca1..d543196 100644 --- a/mail_intake/credentials/store.pyi +++ b/mail_intake/credentials/store.pyi @@ -1,11 +1,11 @@ from abc import ABC, abstractmethod -from typing import Generic, Optional, TypeVar +from typing import Generic, TypeVar T = TypeVar("T") class CredentialStore(ABC, Generic[T]): @abstractmethod - def load(self) -> Optional[T]: ... + def load(self) -> T | None: ... @abstractmethod def save(self, credentials: T) -> None: ... @abstractmethod diff --git a/mail_intake/exceptions.py b/mail_intake/exceptions.py index fd98e0a..62b680d 100644 --- a/mail_intake/exceptions.py +++ b/mail_intake/exceptions.py @@ -1,10 +1,8 @@ """ +# Summary + Exception hierarchy for Mail Intake. ---- - -## Summary - This module defines the **canonical exception types** used throughout the Mail Intake library. diff --git a/mail_intake/ingestion/reader.py b/mail_intake/ingestion/reader.py index 955d70a..25f0522 100644 --- a/mail_intake/ingestion/reader.py +++ b/mail_intake/ingestion/reader.py @@ -16,16 +16,17 @@ It coordinates: No provider-specific logic or API semantics are permitted in this layer. """ +from collections.abc import Iterator from datetime import datetime -from typing import Iterator, Dict, Any +from typing import Any from mail_intake.adapters.base import MailIntakeAdapter +from mail_intake.exceptions import MailIntakeParsingError from mail_intake.models.message import MailIntakeMessage from mail_intake.models.thread import MailIntakeThread -from mail_intake.parsers.headers import parse_headers, extract_sender from mail_intake.parsers.body import extract_body +from mail_intake.parsers.headers import extract_sender, parse_headers from mail_intake.parsers.subject import normalize_subject -from mail_intake.exceptions import MailIntakeParsingError class MailIntakeReader: @@ -87,9 +88,9 @@ class MailIntakeReader: query (str): Provider-specific query string used to filter messages. - Yields: - MailIntakeThread: - An iterator of `MailIntakeThread` instances. + Returns: + Iterator[MailIntakeThread]: + An iterator over `MailIntakeThread` instances. Raises: `MailIntakeParsingError`: @@ -101,7 +102,7 @@ class MailIntakeReader: - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages. """ - threads: Dict[str, MailIntakeThread] = {} + threads: dict[str, MailIntakeThread] = {} for ref in self._adapter.iter_message_refs(query): raw = self._adapter.fetch_message(ref["message_id"]) @@ -119,12 +120,12 @@ class MailIntakeReader: return iter(threads.values()) - def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage: + def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage: """ Parse a raw provider message into a `MailIntakeMessage`. Args: - raw_message (Dict[str, Any]): + raw_message (dict[str, Any]): Provider-native message payload. Returns: diff --git a/mail_intake/ingestion/reader.pyi b/mail_intake/ingestion/reader.pyi index b38852e..fd0e8bb 100644 --- a/mail_intake/ingestion/reader.pyi +++ b/mail_intake/ingestion/reader.pyi @@ -1,4 +1,6 @@ -from typing import Iterator, Dict, Any +from collections.abc import Iterator +from typing import Any + from mail_intake.adapters.base import MailIntakeAdapter from mail_intake.models.message import MailIntakeMessage from mail_intake.models.thread import MailIntakeThread @@ -7,4 +9,4 @@ class MailIntakeReader: def __init__(self, adapter: MailIntakeAdapter) -> None: ... def iter_messages(self, query: str) -> Iterator[MailIntakeMessage]: ... def iter_threads(self, query: str) -> Iterator[MailIntakeThread]: ... - def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage: ... + def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage: ... diff --git a/mail_intake/models/message.py b/mail_intake/models/message.py index 96ea375..d90b339 100644 --- a/mail_intake/models/message.py +++ b/mail_intake/models/message.py @@ -13,7 +13,6 @@ provider-specific fields or semantics. from dataclasses import dataclass from datetime import datetime -from typing import Optional, Dict @dataclass(frozen=True) @@ -54,7 +53,7 @@ class MailIntakeMessage: Sender email address. """ - from_name: Optional[str] + from_name: str | None """ Optional human-readable sender name. """ @@ -74,7 +73,7 @@ class MailIntakeMessage: Short provider-supplied preview snippet of the message. """ - raw_headers: Dict[str, str] + raw_headers: dict[str, str] """ Normalized mapping of message headers (header name β†’ value). """ diff --git a/mail_intake/models/message.pyi b/mail_intake/models/message.pyi index 1b717d0..8c88300 100644 --- a/mail_intake/models/message.pyi +++ b/mail_intake/models/message.pyi @@ -1,14 +1,24 @@ 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] + from_name: str | None 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: ... + raw_headers: dict[str, str] + def __init__( + self, + message_id: str, + thread_id: str, + timestamp: datetime, + from_email: str, + from_name: str | None, + subject: str, + body_text: str, + snippet: str, + raw_headers: dict[str, str], + ) -> None: ... diff --git a/mail_intake/models/thread.py b/mail_intake/models/thread.py index 199da26..10cb303 100644 --- a/mail_intake/models/thread.py +++ b/mail_intake/models/thread.py @@ -12,7 +12,6 @@ for higher-level correspondence workflows. from dataclasses import dataclass, field from datetime import datetime -from typing import List, Set from mail_intake.models.message import MailIntakeMessage @@ -42,12 +41,12 @@ class MailIntakeThread: Normalized subject line used to group related messages. """ - participants: Set[str] = field(default_factory=set) + participants: set[str] = field(default_factory=set) """ Set of unique participant email addresses observed in the thread. """ - messages: List[MailIntakeMessage] = field(default_factory=list) + messages: list[MailIntakeMessage] = field(default_factory=list) """ Ordered list of messages belonging to this thread. """ diff --git a/mail_intake/models/thread.pyi b/mail_intake/models/thread.pyi index 0fe0541..5b4af80 100644 --- a/mail_intake/models/thread.pyi +++ b/mail_intake/models/thread.pyi @@ -1,12 +1,19 @@ 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: ... + participants: set[str] + messages: list[MailIntakeMessage] + last_activity_at: datetime | None + def __init__( + self, + thread_id: str, + normalized_subject: str, + participants: set[str] = ..., + messages: list[MailIntakeMessage] = ..., + last_activity_at: datetime | None = ..., + ) -> None: ... def add_message(self, message: MailIntakeMessage) -> None: ... diff --git a/mail_intake/parsers/__init__.pyi b/mail_intake/parsers/__init__.pyi index 0238a34..15c4f2a 100644 --- a/mail_intake/parsers/__init__.pyi +++ b/mail_intake/parsers/__init__.pyi @@ -1,5 +1,5 @@ from .body import extract_body -from .headers import parse_headers, extract_sender +from .headers import extract_sender, parse_headers from .subject import normalize_subject __all__ = ["extract_body", "parse_headers", "extract_sender", "normalize_subject"] diff --git a/mail_intake/parsers/body.py b/mail_intake/parsers/body.py index 675b811..4aa5f2f 100644 --- a/mail_intake/parsers/body.py +++ b/mail_intake/parsers/body.py @@ -11,7 +11,7 @@ prefers human-readable text over fidelity to original formatting. """ import base64 -from typing import Dict, Any, Optional +from typing import Any from bs4 import BeautifulSoup @@ -45,7 +45,7 @@ def _decode_base64(data: str) -> str: raise MailIntakeParsingError("Failed to decode message body") from exc -def _extract_from_part(part: Dict[str, Any]) -> Optional[str]: +def _extract_from_part(part: dict[str, Any]) -> str | None: """ Extract text content from a single MIME part. @@ -55,11 +55,11 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]: - `text/html` (converted to plain text) Args: - part (Dict[str, Any]): + part (dict[str, Any]): MIME part dictionary from a provider payload. Returns: - Optional[str]: + str | None: Extracted plain-text content, or `None` if unsupported or empty. """ mime_type = part.get("mimeType") @@ -82,7 +82,7 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]: return None -def extract_body(payload: Dict[str, Any]) -> str: +def extract_body(payload: dict[str, Any]) -> str: """ Extract the best-effort message body from a Gmail payload. @@ -94,7 +94,7 @@ def extract_body(payload: Dict[str, Any]) -> str: 4. Empty string (if nothing usable found) Args: - payload (Dict[str, Any]): + payload (dict[str, Any]): Provider-native message payload dictionary. Returns: diff --git a/mail_intake/parsers/body.pyi b/mail_intake/parsers/body.pyi index f13004f..81c785f 100644 --- a/mail_intake/parsers/body.pyi +++ b/mail_intake/parsers/body.pyi @@ -1,3 +1,3 @@ -from typing import Dict, Any +from typing import Any -def extract_body(payload: Dict[str, Any]) -> str: ... +def extract_body(payload: dict[str, Any]) -> str: ... diff --git a/mail_intake/parsers/headers.py b/mail_intake/parsers/headers.py index c3ce864..4f1ac82 100644 --- a/mail_intake/parsers/headers.py +++ b/mail_intake/parsers/headers.py @@ -10,19 +10,17 @@ The functions here are intentionally simple and tolerant of malformed or incomplete header data. """ -from typing import Dict, List, Tuple, Optional - -def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]: +def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]: """ Convert a list of Gmail-style headers into a normalized dict. Args: - raw_headers (List[Dict[str, str]]): + raw_headers (list[dict[str, str]]): List of header dictionaries, each containing `name` and `value` keys. Returns: - Dict[str, str]: + dict[str, str]: Dictionary mapping lowercase header names to stripped values. Notes: @@ -50,7 +48,7 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]: } ``` """ - headers: Dict[str, str] = {} + headers: dict[str, str] = {} for header in raw_headers or []: name = header.get("name") @@ -64,16 +62,16 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]: return headers -def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]: +def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]: """ Extract sender email and optional display name from headers. Args: - headers (Dict[str, str]): + headers (dict[str, str]): Normalized header dictionary as returned by `parse_headers()`. Returns: - Tuple[str, Optional[str]]: + tuple[str, str | None]: A tuple `(email, name)` where `email` is the sender email address and `name` is the display name, or `None` if unavailable. diff --git a/mail_intake/parsers/headers.pyi b/mail_intake/parsers/headers.pyi index f819ae7..9238421 100644 --- a/mail_intake/parsers/headers.pyi +++ b/mail_intake/parsers/headers.pyi @@ -1,4 +1,2 @@ -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]]: ... +def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]: ... +def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]: ... diff --git a/mail_intake/parsers/subject.py b/mail_intake/parsers/subject.py index aa565d8..eb1f23b 100644 --- a/mail_intake/parsers/subject.py +++ b/mail_intake/parsers/subject.py @@ -12,7 +12,6 @@ meaning while removing common reply and forward prefixes. import re - _PREFIX_RE = re.compile(r"^(re|fw|fwd)\s*:\s*", re.IGNORECASE) """ Regular expression matching common reply/forward subject prefixes. diff --git a/mail_intake/py.typed b/mail_intake/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/mcp_docs/modules/mail_intake.adapters.base.json b/mcp_docs/modules/mail_intake.adapters.base.json deleted file mode 100644 index 442d30b..0000000 --- a/mcp_docs/modules/mail_intake.adapters.base.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "module": "mail_intake.adapters.base", - "content": { - "path": "mail_intake.adapters.base", - "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.", - "objects": { - "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\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.", - "members": { - "iter_message_refs": { - "name": "iter_message_refs", - "kind": "function", - "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", - "signature": "", - "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```" - }, - "fetch_message": { - "name": "fetch_message", - "kind": "function", - "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", - "signature": "", - "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)." - }, - "fetch_thread": { - "name": "fetch_thread", - "kind": "function", - "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", - "signature": "", - "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload." - } - } - } - } - } -} \ 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 deleted file mode 100644 index cefc472..0000000 --- a/mcp_docs/modules/mail_intake.parsers.body.json +++ /dev/null @@ -1,58 +0,0 @@ -{ - "module": "mail_intake.parsers.body", - "content": { - "path": "mail_intake.parsers.body", - "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.", - "objects": { - "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\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models." - }, - "extract_body": { - "name": "extract_body", - "kind": "function", - "path": "mail_intake.parsers.body.extract_body", - "signature": "", - "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body." - } - } - } -} \ 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 deleted file mode 100644 index 0b32806..0000000 --- a/mcp_docs/modules/mail_intake.parsers.headers.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "module": "mail_intake.parsers.headers", - "content": { - "path": "mail_intake.parsers.headers", - "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.", - "objects": { - "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\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe \"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe \",\n \"subject\": \"Re: Interview Update\",\n }\n ```" - }, - "extract_sender": { - "name": "extract_sender", - "kind": "function", - "path": "mail_intake.parsers.headers.extract_sender", - "signature": "", - "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe \"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`" - } - } - } -} \ No newline at end of file diff --git a/mcp_docs/nav.json b/mcp_docs/nav.json deleted file mode 100644 index 10e1093..0000000 --- a/mcp_docs/nav.json +++ /dev/null @@ -1,90 +0,0 @@ -[ - { - "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/pyproject.toml b/pyproject.toml index 1b4d737..2b492fa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "mail-intake" -version = "0.0.2" +version = "0.0.3" description = "Structured mail ingestion and correspondence parsing with provider adapters (Gmail-first)." readme = "README.md" requires-python = ">=3.10" @@ -37,17 +37,18 @@ classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", "Topic :: Communications :: Email", "Topic :: Software Development :: Libraries", + "Typing :: Typed", ] + dependencies = [ - # Gmail API stack "google-api-python-client>=2.120.0", "google-auth>=2.28.0", "google-auth-oauthlib>=1.2.0", - # Parsing "beautifulsoup4>=4.12.0", "lxml>=5.1.0", ] @@ -56,15 +57,26 @@ dependencies = [ [project.optional-dependencies] dev = [ "pytest>=8.0.0", + "pytest-asyncio>=0.21.0", "pytest-cov>=4.1.0", + "black>=23.0.0", "ruff>=0.3.0", "mypy>=1.8.0", + "build>=1.0.0", + "twine>=4.0.0", + "pre-commit>=3.4.0", "types-beautifulsoup4", + "doc-forge[mcp,mkdocs]>=0.0.6", ] docs = [ "mkdocs>=1.5.0", "mkdocs-material>=9.5.0", + "mkdocstrings[python]>=0.24.0", +] + +all = [ + "mail-intake[dev,docs]", ] @@ -79,12 +91,110 @@ Versions = "https://git.aetoskia.com/aetos/mail-intake/tags" [tool.setuptools] packages = { find = { include = ["mail_intake*"] } } +[tool.setuptools.package-data] +mail_intake = ["py.typed"] + + +[tool.pytest.ini_options] +testpaths = ["tests"] +asyncio_mode = "auto" +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = [ + "--strict-markers", + "--strict-config", + "--cov=mail_intake", + "--cov-report=term-missing", + "--cov-report=html", + "--cov-report=xml", +] + + +[tool.black] +line-length = 88 +target-version = ["py310", "py311", "py312", "py313"] +include = '\.pyi?$' +extend-exclude = ''' +fetch_emails\.py$ | /( + \.eggs + | \.git + | \.hg + | \.mypy_cache + | \.tox + | \.venv + | build + | dist +)/ +''' + [tool.ruff] -line-length = 100 +line-length = 88 target-version = "py310" +exclude = ["fetch_emails.py"] + +[tool.ruff.lint] +select = [ + "E", + "W", + "F", + "I", + "B", + "C4", + "UP", +] +ignore = [ + "E501", + "B008", + "C901", +] + +[tool.ruff.lint.per-file-ignores] +"__init__.py" = ["F401", "I001"] +"tests/*" = ["B008"] + [tool.mypy] python_version = "3.10" strict = true +exclude = [ + "tests/", +] +files = ["mail_intake"] + +[[tool.mypy.overrides]] +module = [ + "google.*", + "googleapiclient.*", + "bs4.*", + "lxml.*", +] ignore_missing_imports = true + + +[tool.pydoclint] +style = "google" +exclude = '\.pyi$|tests/' +allow-init-docstring = true +skip-checking-raises = true +check-class-attributes = false + + +[tool.coverage.run] +source = ["mail_intake"] +omit = [ + "*/tests/*", + "*/test_*.py", +] + +[tool.coverage.report] +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "if __name__ == .__main__.:", + "raise AssertionError", + "raise NotImplementedError", + "if TYPE_CHECKING:", + "@abstractmethod", +] \ No newline at end of file diff --git a/tests/unit/test_models.py b/tests/unit/test_models.py index f8dc811..b9dc8fe 100644 --- a/tests/unit/test_models.py +++ b/tests/unit/test_models.py @@ -1,7 +1,6 @@ from datetime import datetime, timedelta -from mail_intake.models import MailIntakeMessage -from mail_intake.models import MailIntakeThread +from mail_intake.models import MailIntakeMessage, MailIntakeThread def test_message_is_immutable(): @@ -19,7 +18,7 @@ def test_message_is_immutable(): try: msg.subject = "Changed" - assert False, "Message should be immutable" + raise AssertionError("Message should be immutable") except Exception: assert True diff --git a/tests/unit/test_parsers.py b/tests/unit/test_parsers.py index 026090f..3b16a25 100644 --- a/tests/unit/test_parsers.py +++ b/tests/unit/test_parsers.py @@ -1,8 +1,11 @@ import base64 -from mail_intake.parsers import normalize_subject -from mail_intake.parsers import parse_headers, extract_sender -from mail_intake.parsers import extract_body +from mail_intake.parsers import ( + extract_body, + extract_sender, + normalize_subject, + parse_headers, +) def _b64(text: str) -> str: @@ -13,6 +16,7 @@ def _b64(text: str) -> str: # Subject parsing # -------------------- + def test_normalize_subject_strips_common_prefixes(): assert normalize_subject("Re: Interview Update") == "Interview Update" assert normalize_subject("Fwd: Re: Offer Letter") == "Offer Letter" @@ -32,6 +36,7 @@ def test_normalize_subject_empty_and_none_safe(): # Header parsing # -------------------- + def test_parse_headers_lowercases_keys(): raw_headers = [ {"name": "From", "value": "Alice "}, @@ -82,6 +87,7 @@ def test_extract_sender_missing_from(): # Body parsing # -------------------- + def test_extract_body_prefers_text_plain(): payload = { "parts": [ @@ -116,9 +122,7 @@ def test_extract_body_falls_back_to_html(): def test_extract_body_single_part(): - payload = { - "body": {"data": _b64("Single part body")} - } + payload = {"body": {"data": _b64("Single part body")}} body = extract_body(payload) assert body == "Single part body"