abstractcore 2.19.2__tar.gz → 2.20.0__tar.gz

{abstractcore-2.19.2 → abstractcore-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.19.2
+Version: 2.20.0
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>
@@ -48,6 +48,8 @@ Requires-Dist: fastapi<1.0.0,>=0.100.0
 Requires-Dist: uvicorn[standard]<1.0.0,>=0.23.0
 Requires-Dist: python-multipart<1.0.0,>=0.0.6
 Requires-Dist: sse-starlette<2.0.0,>=1.6.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: keyring>=24.0.0
 Requires-Dist: abstractvoice>=0.13.2
 Requires-Dist: abstractvision>=0.3.33
 Requires-Dist: abstractmusic>=0.1.15; python_version >= "3.10"
@@ -173,6 +175,7 @@ Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: responses>=0.23.0; extra == "test"
 Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "test"
 Requires-Dist: jinja2<4.0.0,>=3.0.0; extra == "test"
+Requires-Dist: aiosmtpd<2.0.0,>=1.4.4; extra == "test"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5.0; extra == "docs"
 Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
@@ -452,6 +455,7 @@ You can also persist settings (including API keys) via the config CLI:
 - Embeddings and semantic search → [Embeddings](docs/embeddings.md)
 - Observability: global event bus + interaction traces → [Architecture](docs/architecture.md), [API Reference (Events)](docs/api-reference.md#eventtype), [Interaction Tracing](docs/interaction-tracing.md)
 - MCP (Model Context Protocol): discover tools from MCP servers (HTTP/stdio) → [MCP](docs/mcp.md)
+- Email: one IMAP/SMTP account (password or OAuth2), encrypted credentials, recipient policy, send limits, read-only mailbox and email tools → [Email](docs/email.md)
 - OpenAI-compatible server: one `/v1` gateway for chat + optional `/v1/images/*` and `/v1/audio/*` endpoints → [Server](docs/server.md)
 
 ## Tool calling (passthrough by default)
@@ -721,6 +725,15 @@ abstractcore engines status --probe              # Ollama / LM Studio / MLX / ll
 abstractcore engines install ollama --dry-run    # the exact install command
 ```
 
+Email (see [Email](docs/email.md)):
+
+```bash
+abstractcore email connect --address me@example.com \
+  --imap-host imap.example.com --smtp-host smtp.example.com --password <value>
+abstractcore email test
+abstractcore email status
+```
+
 ## Built-in CLI apps
 
 AbstractCore also ships with ready-to-use CLI apps:
@@ -759,6 +772,7 @@ Core features:
 - [Capabilities](docs/capabilities.md) — supported features and current limitations
 - [Interaction Tracing](docs/interaction-tracing.md) — inspect prompts/responses/usage for observability
 - [MCP](docs/mcp.md) — consume MCP tool servers (HTTP/stdio) as tool sources
+- [Email](docs/email.md) — connect a mailbox, recipient policy, send limits, email tools and the `abstractcore.comms.email` library
 
 Reference and internals:
 - [Architecture](docs/architecture.md) — system overview + event system

{abstractcore-2.19.2 → abstractcore-2.20.0}/README.md

@@ -270,6 +270,7 @@ You can also persist settings (including API keys) via the config CLI:
 - Embeddings and semantic search → [Embeddings](docs/embeddings.md)
 - Observability: global event bus + interaction traces → [Architecture](docs/architecture.md), [API Reference (Events)](docs/api-reference.md#eventtype), [Interaction Tracing](docs/interaction-tracing.md)
 - MCP (Model Context Protocol): discover tools from MCP servers (HTTP/stdio) → [MCP](docs/mcp.md)
+- Email: one IMAP/SMTP account (password or OAuth2), encrypted credentials, recipient policy, send limits, read-only mailbox and email tools → [Email](docs/email.md)
 - OpenAI-compatible server: one `/v1` gateway for chat + optional `/v1/images/*` and `/v1/audio/*` endpoints → [Server](docs/server.md)
 
 ## Tool calling (passthrough by default)
@@ -539,6 +540,15 @@ abstractcore engines status --probe              # Ollama / LM Studio / MLX / ll
 abstractcore engines install ollama --dry-run    # the exact install command
 ```
 
+Email (see [Email](docs/email.md)):
+
+```bash
+abstractcore email connect --address me@example.com \
+  --imap-host imap.example.com --smtp-host smtp.example.com --password <value>
+abstractcore email test
+abstractcore email status
+```
+
 ## Built-in CLI apps
 
 AbstractCore also ships with ready-to-use CLI apps:
@@ -577,6 +587,7 @@ Core features:
 - [Capabilities](docs/capabilities.md) — supported features and current limitations
 - [Interaction Tracing](docs/interaction-tracing.md) — inspect prompts/responses/usage for observability
 - [MCP](docs/mcp.md) — consume MCP tool servers (HTTP/stdio) as tool sources
+- [Email](docs/email.md) — connect a mailbox, recipient policy, send limits, email tools and the `abstractcore.comms.email` library
 
 Reference and internals:
 - [Architecture](docs/architecture.md) — system overview + event system

abstractcore-2.20.0/abstractcore/comms/__init__.py

@@ -0,0 +1,5 @@
+"""Communication libraries (typed, host-agnostic).
+
+`abstractcore.comms.email` is the one implementation of mail in the framework: the core
+CLI, the core tools, the consoles and hosts such as the gateway all use it.
+"""

abstractcore-2.20.0/abstractcore/comms/email/__init__.py

@@ -0,0 +1,156 @@
+"""`abstractcore.comms.email` — the framework's one mail implementation.
+
+    from abstractcore.comms.email import (
+        EmailAccount, ImapSettings, SmtpSettings, EmailSecret, EmailClient,
+        EmailAccountStore, RecipientPolicy, SendLimits, SearchCriteria, OutgoingMessage,
+    )
+
+    account = EmailAccount.build(
+        address="me@example.test",
+        imap=ImapSettings.build("imap.example.test", security="ssl"),
+        smtp=SmtpSettings.build("smtp.example.test", security="starttls"),
+    )
+    store = EmailAccountStore()                     # the local AbstractCore settings
+    store.connect(account, EmailSecret("app-password"))
+    ctx = store.context()
+    ctx.client().search(SearchCriteria.build(unseen=True, since="7d"), limit=20)
+    ctx.send(OutgoingMessage(to=("me@example.test",), subject="Hello", text="Hi"))
+
+Modules: `models` (typed settings), `client` (IMAP read-only + SMTP, verified TLS),
+`bodystructure` (the MIME structure used to fetch only the parts needed),
+`policy` (recipient allowlist / denylist), `limits` (send rate limits), `vault` (encrypted
+credentials), `oauth` (OAuth2 / XOAUTH2), `store` (settings + secret + status), `context`
+(the guarded send), `errors` (typed errors), `legacy` (one-time import of pre-2.20 settings).
+"""
+
+from .client import DEFAULT_MAX_MESSAGE_BYTES, MAX_LIST_LIMIT, EmailClient, tls_context
+from .context import EmailContext, guarded_send
+from .errors import (
+    EmailAgentToolsOff,
+    EmailAttachmentNotFound,
+    EmailAuthFailed,
+    EmailDisabled,
+    EmailError,
+    EmailInvalidMessage,
+    EmailInvalidSettings,
+    EmailMailboxMissing,
+    EmailMessageNotFound,
+    EmailMessageTooLarge,
+    EmailNotConfigured,
+    EmailOAuthFailed,
+    EmailOAuthPending,
+    EmailOAuthReauthorize,
+    EmailPolicyRefused,
+    EmailProtocolError,
+    EmailQuotaExceeded,
+    EmailRateLimited,
+    EmailReadOnlyViolation,
+    EmailRecipientRefused,
+    EmailSecretUnavailable,
+    EmailServerError,
+    EmailTlsFailed,
+    EmailTransient,
+    EmailUnreachable,
+)
+from .limits import SendRateLimiter
+from .models import (
+    Attachment,
+    AttachmentInfo,
+    EmailAccount,
+    EmailSecret,
+    FetchResult,
+    ImapSettings,
+    MailCursor,
+    MessageDetail,
+    MessageSummary,
+    OAuthSettings,
+    OutgoingMessage,
+    SendLimits,
+    SendResult,
+    SmtpSettings,
+)
+from .oauth import (
+    BUILTIN_CLIENTS,
+    DeviceAuthorization,
+    LoopbackAuthorization,
+    OAuthTokenClient,
+    OAuthTokenProvider,
+    TokenSet,
+    builtin_client,
+    provider_preset,
+    resolve_oauth_client,
+    xoauth2_string,
+)
+from .policy import PolicyDecision, RecipientPolicy, evaluate, normalize_address, normalize_domain, parse_recipients
+from .search import SearchCriteria
+from .store import EmailAccountStore, EmailSettings
+from .vault import SecretVault
+
+__all__ = [
+    "DEFAULT_MAX_MESSAGE_BYTES",
+    "MAX_LIST_LIMIT",
+    "BUILTIN_CLIENTS",
+    "Attachment",
+    "AttachmentInfo",
+    "DeviceAuthorization",
+    "EmailAccount",
+    "EmailAccountStore",
+    "EmailAgentToolsOff",
+    "EmailAttachmentNotFound",
+    "EmailAuthFailed",
+    "EmailClient",
+    "EmailContext",
+    "EmailDisabled",
+    "EmailError",
+    "EmailInvalidMessage",
+    "EmailInvalidSettings",
+    "EmailMailboxMissing",
+    "EmailMessageNotFound",
+    "EmailMessageTooLarge",
+    "EmailNotConfigured",
+    "EmailOAuthFailed",
+    "EmailOAuthPending",
+    "EmailOAuthReauthorize",
+    "EmailPolicyRefused",
+    "EmailProtocolError",
+    "EmailQuotaExceeded",
+    "EmailRateLimited",
+    "EmailReadOnlyViolation",
+    "EmailRecipientRefused",
+    "EmailSecret",
+    "EmailSecretUnavailable",
+    "EmailServerError",
+    "EmailSettings",
+    "EmailTlsFailed",
+    "EmailTransient",
+    "EmailUnreachable",
+    "FetchResult",
+    "ImapSettings",
+    "LoopbackAuthorization",
+    "MailCursor",
+    "MessageDetail",
+    "MessageSummary",
+    "OAuthSettings",
+    "OAuthTokenClient",
+    "OAuthTokenProvider",
+    "OutgoingMessage",
+    "PolicyDecision",
+    "RecipientPolicy",
+    "SearchCriteria",
+    "SecretVault",
+    "SendLimits",
+    "SendRateLimiter",
+    "SendResult",
+    "SmtpSettings",
+    "TokenSet",
+    "builtin_client",
+    "evaluate",
+    "guarded_send",
+    "normalize_address",
+    "normalize_domain",
+    "parse_recipients",
+    "provider_preset",
+    "resolve_oauth_client",
+    "tls_context",
+    "xoauth2_string",
+]

abstractcore-2.20.0/abstractcore/comms/email/bodystructure.py

@@ -0,0 +1,253 @@
+"""IMAP BODYSTRUCTURE (RFC 3501 section 7.4.2): the MIME tree of a message without its content.
+
+Reading a message fetches its structure first, then only the parts it needs by section
+(`BODY.PEEK[1.2]`): the text/plain and text/html bodies for `read_email`, one part for an
+attachment download. Attachments are listed from the structure (name, type, size) without
+downloading them.
+
+The parser follows the RFC grammar (parenthesised lists, strings, NIL); it never looks for
+words in free text. Section numbers follow RFC 3501 section 6.4.5: the parts of a multipart
+body are numbered 1, 2, ... (nested: 2.1, 2.2); a message that is not multipart has its body at
+section 1; the parts inside an attached message (message/rfc822 at section 2) are 2.1, 2.2, ...
+(its body is 2.1 when it is not multipart).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import email.header
+import email.utils
+import quopri
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class MimePart:
+    """One node of the structure. `size` is the part's size on the wire (encoded octets)."""
+
+    section: str
+    content_type: str
+    params: Dict[str, str] = field(default_factory=dict)
+    content_id: str = ""
+    encoding: str = ""
+    size: int = 0
+    disposition: str = ""
+    disposition_params: Dict[str, str] = field(default_factory=dict)
+    children: Tuple["MimePart", ...] = ()
+    # message/rfc822 only: the body of the attached message.
+    message_body: Optional["MimePart"] = None
+
+    @property
+    def multipart(self) -> bool:
+        return self.content_type.startswith("multipart/")
+
+    @property
+    def charset(self) -> str:
+        return self.params.get("charset", "")
+
+    @property
+    def filename(self) -> str:
+        return self.disposition_params.get("filename") or self.params.get("name") or ""
+
+    @property
+    def is_attachment(self) -> bool:
+        """Same rule as reading the whole message did: disposition `attachment`, or a file name."""
+
+        if self.multipart:
+            return False
+        return self.disposition == "attachment" or bool(self.filename)
+
+
+def _text(tok: Any) -> str:
+    if tok is None:
+        return ""
+    if isinstance(tok, (bytes, bytearray)):
+        return bytes(tok).decode("utf-8", errors="replace")
+    return str(tok)
+
+
+def _decode_words(value: str) -> str:
+    """RFC 2047 encoded words (`=?utf-8?B?...?=`) inside a parameter value, if any."""
+
+    if "=?" not in value:
+        return value
+    try:
+        return str(email.header.make_header(email.header.decode_header(value)))
+    except (ValueError, LookupError, UnicodeDecodeError, binascii.Error):
+        return value
+
+
+def _params(tok: Any) -> Dict[str, str]:
+    """A parameter list `("NAME" "value" ...)` -> {name: decoded value}.
+
+    RFC 2231 forms (`filename*`, continuations `filename*0*`) are decoded with the standard
+    library; RFC 2047 encoded words are decoded too.
+    """
+
+    if not isinstance(tok, list):
+        return {}
+    pairs: List[Tuple[str, str]] = []
+    for i in range(0, len(tok) - 1, 2):
+        key = _text(tok[i]).strip().lower()
+        if key:
+            value = _text(tok[i + 1])
+            if not key.endswith("*"):
+                # decode_params unquotes; keep the value as the server sent it.
+                value = '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+            pairs.append((key, value))
+    if not pairs:
+        return {}
+    try:
+        decoded = email.utils.decode_params([("", "")] + pairs)[1:]
+    except Exception:  # noqa: BLE001 - a malformed parameter list reads as "no parameters"
+        decoded = [(k.rstrip("*"), v.strip('"')) for k, v in pairs]
+    out: Dict[str, str] = {}
+    for key, value in decoded:
+        if isinstance(value, tuple):
+            charset, language, encoded = value
+            text = email.utils.collapse_rfc2231_value((charset, language, email.utils.unquote(encoded)))
+        else:
+            text = _decode_words(email.utils.unquote(str(value)))
+        out[str(key).lower()] = str(text)
+    return out
+
+
+def _disposition(tok: Any) -> Tuple[str, Dict[str, str]]:
+    if isinstance(tok, list) and tok:
+        return _text(tok[0]).strip().lower(), _params(tok[1] if len(tok) > 1 else None)
+    return "", {}
+
+
+def _int(tok: Any) -> int:
+    try:
+        return int(_text(tok).strip())
+    except ValueError:
+        return 0
+
+
+def _part_at(tok: Any, section: str) -> MimePart:
+    """The part described by `tok`, located at `section`."""
+
+    if not isinstance(tok, list) or not tok:
+        raise ValueError("BODYSTRUCTURE part is not a list")
+    if isinstance(tok[0], list):
+        # multipart: (part)(part)... "SUBTYPE" [params [disposition [language [location]]]]
+        children: List[MimePart] = []
+        i = 0
+        while i < len(tok) and isinstance(tok[i], list):
+            children.append(_part_at(tok[i], f"{section}.{len(children) + 1}" if section else str(len(children) + 1)))
+            i += 1
+        subtype = _text(tok[i]).lower() if i < len(tok) else "mixed"
+        params = _params(tok[i + 1]) if i + 1 < len(tok) else {}
+        disp, dparams = _disposition(tok[i + 2]) if i + 2 < len(tok) else ("", {})
+        return MimePart(
+            section=section,
+            content_type=f"multipart/{subtype}",
+            params=params,
+            disposition=disp,
+            disposition_params=dparams,
+            children=tuple(children),
+        )
+    # single part: type subtype params id description encoding size ...
+    if len(tok) < 7:
+        raise ValueError("BODYSTRUCTURE part is too short")
+    ctype = f"{_text(tok[0]).lower()}/{_text(tok[1]).lower()}"
+    rest = list(tok[7:])
+    message_body: Optional[MimePart] = None
+    if ctype == "message/rfc822" and len(rest) >= 3:
+        # envelope, body, lines
+        message_body = _message_body(rest[1], section)
+        rest = rest[3:]
+    elif ctype.startswith("text/") and rest:
+        rest = rest[1:]  # lines
+    # extension data: md5 disposition language location
+    disp, dparams = _disposition(rest[1]) if len(rest) > 1 else ("", {})
+    return MimePart(
+        section=section,
+        content_type=ctype,
+        params=_params(tok[2]),
+        content_id=_text(tok[3]).strip(),
+        encoding=_text(tok[5]).strip().lower(),
+        size=_int(tok[6]),
+        disposition=disp,
+        disposition_params=dparams,
+        message_body=message_body,
+    )
+
+
+def _message_body(tok: Any, prefix: str) -> MimePart:
+    """The body of a message (the top level, or an attached message at section `prefix`)."""
+
+    if isinstance(tok, list) and tok and isinstance(tok[0], list):
+        return _part_at(tok, prefix)
+    return _part_at(tok, f"{prefix}.1" if prefix else "1")
+
+
+def parse_bodystructure(tok: Any) -> MimePart:
+    """The root of a message's structure from the parsed `BODYSTRUCTURE` value."""
+
+    return _message_body(tok, "")
+
+
+def walk(part: MimePart) -> Iterator[MimePart]:
+    """Depth-first, in document order. An attached message (message/rfc822 with disposition
+    `attachment`) is one attachment; an inline one is walked into."""
+
+    yield part
+    for child in part.children:
+        yield from walk(child)
+    if part.message_body is not None and not part.is_attachment:
+        yield from walk(part.message_body)
+
+
+def body_parts(root: MimePart) -> List[MimePart]:
+    """The text/plain and text/html parts that are not attachments, in document order."""
+
+    return [
+        p
+        for p in walk(root)
+        if not p.multipart
+        and p.message_body is None
+        and not p.is_attachment
+        and p.content_type in ("text/plain", "text/html")
+    ]
+
+
+def attachment_parts(root: MimePart) -> List[MimePart]:
+    return [p for p in walk(root) if p.is_attachment]
+
+
+def decode_transfer(data: bytes, encoding: str) -> bytes:
+    """Undo the Content-Transfer-Encoding of a part's wire bytes."""
+
+    enc = (encoding or "").strip().lower()
+    if enc == "base64":
+        try:
+            return base64.b64decode(data, validate=False)
+        except (binascii.Error, ValueError):
+            return base64.b64decode(data + b"=" * (-len(data) % 4), validate=False)
+    if enc == "quoted-printable":
+        return quopri.decodestring(data)
+    return bytes(data)
+
+
+def decode_text(data: bytes, part: MimePart) -> str:
+    raw = decode_transfer(data, part.encoding)
+    charset = part.charset or "utf-8"
+    try:
+        return raw.decode(charset, errors="replace")
+    except LookupError:
+        return raw.decode("utf-8", errors="replace")
+
+
+__all__ = [
+    "MimePart",
+    "attachment_parts",
+    "body_parts",
+    "decode_text",
+    "decode_transfer",
+    "parse_bodystructure",
+    "walk",
+]