openmail 0.1.5__py3-none-any.whl

openmail/assistants/prioritize_emails.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Sequence, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+PRIORITIZE_EMAILS_PROMPT = """
+You are an assistant that assigns a priority score to each email.
+
+Consider:
+- Urgency and explicit deadlines.
+- Importance of the sender (e.g., manager, key client vs. newsletter).
+- Clear requests for action or decision.
+- Relevance to ongoing work or commitments.
+
+Instructions:
+- Each email is identified by an Email ID.
+- For each email, you must output:
+  - id: the Email ID (copied exactly as given)
+  - score: a numeric priority score between 0.0 and 1.0
+    - 1.0 = extremely urgent and important
+    - 0.0 = trivial / ignorable
+- Base the score only on the email content and metadata provided.
+- Do not omit any email; produce one item for every Email ID.
+
+Emails:
+{email_blocks}
+"""
+
+
+class EmailPriorityItem(BaseModel):
+    id: str = Field(
+        description="Opaque ID that identifies one email exactly as given in the prompt."
+    )
+    score: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="Priority score between 0.0 (trivial) and 1.0 (critical).",
+    )
+
+
+class EmailPrioritySchema(BaseModel):
+    items: List[EmailPriorityItem] = Field(
+        description=(
+            "List of priority results. Each item contains an email id and a score. "
+            "There must be one item per email."
+        )
+    )
+
+
+def llm_prioritize_emails(
+    messages: Sequence[EmailMessage],
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[List[float], Dict[str, Any]]:
+    """
+    Assign a priority score to multiple emails at once.
+    """
+    if not messages:
+        return [], {}
+
+    id_list = [f"e{i + 1}" for i in range(len(messages))]
+    id_to_index = {id_: i for i, id_ in enumerate(id_list)}
+
+    email_blocks = "\n\n".join(
+        f"Email ID: {email_id}\n{build_email_context(msg)}"
+        for email_id, msg in zip(id_list, messages)
+    )
+
+    prompt = PRIORITIZE_EMAILS_PROMPT.format(
+        email_blocks=email_blocks,
+    )
+
+    chain = get_model(provider, model_name, EmailPrioritySchema)
+    result, llm_call_info = chain(prompt)
+
+    # Preserve order of input messages
+    scores: List[float] = [0.0] * len(messages)
+    for item in result.items:
+        idx = id_to_index.get(item.id)
+        if idx is not None:
+            scores[idx] = item.score
+
+    return scores, llm_call_info

openmail/assistants/reply.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+EMAIL_REPLY_PROMPT = """
+You are an assistant that drafts concise, polite email replies.
+
+The previous suggested reply (for reference or editing):
+{previous_reply}
+
+The user's instruction about how to change or generate the reply:
+{reply_context}
+
+Instructions (follow all):
+- Either improve/refine the previous reply, or write a new one if needed.
+- Follow the user's instruction above as much as possible.
+- Be professional but friendly.
+- Keep it short and to the point.
+- Do NOT explain what you are doing.
+- Output ONLY the email reply body text (no surrounding quotes).
+
+Email context:
+{email_context}
+"""
+
+
+class EmailReplySchema(BaseModel):
+    reply: str = Field(description="A concise reply body for the email.")
+
+
+def llm_concise_reply_for_email(
+    reply_context: str,
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+    previous_reply: Optional[str] = None,
+) -> Tuple[str, dict[str, Any]]:
+    """
+    Generate a concise email reply using the LLM pipeline.
+    """
+    chain = get_model(provider, model_name, EmailReplySchema)
+    email_context = build_email_context(msg)
+    result, llm_call_info = chain(
+        EMAIL_REPLY_PROMPT.format(
+            previous_reply=previous_reply or "",
+            reply_context=reply_context,
+            email_context=email_context,
+        )
+    )
+
+    return result.reply, llm_call_info

openmail/assistants/reply_suggestions.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, List, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+EMAIL_REPLY_SUGGESTION_PROMPT = """
+You are an assistant that generates brief suggestions for how a user could reply to an email.
+
+Instructions:
+- Provide 2 to 3 distinct reply strategies.
+- Each suggestion must be short (4 to 10 words).
+- Describe the intent of the reply, NOT the reply text itself.
+- No numbering, no bullets, no quotes, no commentary.
+- Separate each suggestion with a blank line.
+
+Email context:
+{email_context}
+"""
+
+
+class EmailReplySuggestionsSchema(BaseModel):
+    suggestions: List[str] = Field(description="2-3 concise suggestions describing how to reply.")
+
+
+def llm_reply_suggestions_for_email(
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[List[str], dict[str, Any]]:
+    """
+    Generate 2-3 short reply suggestions using the LLM pipeline.
+    """
+    chain = get_model(provider, model_name, EmailReplySuggestionsSchema)
+    email_context = build_email_context(msg)
+    result, llm_call_info = chain(
+        EMAIL_REPLY_SUGGESTION_PROMPT.format(
+            email_context=email_context,
+        )
+    )
+    return result.suggestions, llm_call_info

openmail/assistants/rewrite_email.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+
+REWRITE_EMAIL_PROMPT = """
+You are an assistant that rewrites email drafts while preserving the original meaning.
+
+Instructions:
+- Rewrite the email using the requested style.
+- Preserve all important facts, commitments, and dates.
+- Keep the structure of an email (greeting, body, closing) if present.
+- Do not add new information that is not implied by the original.
+- Do not include any explanation; only output the rewritten email text.
+
+Requested style:
+{style}
+
+Original email:
+{draft}
+"""
+
+
+class RewriteEmailSchema(BaseModel):
+    rewritten_email: str = Field(
+        description="The full email text rewritten in the requested style."
+    )
+
+
+def llm_rewrite_email(
+    draft_text: str,
+    style: str,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[str, dict[str, Any]]:
+    """
+    Rewrite an email draft according to a requested style.
+    """
+    chain = get_model(provider, model_name, RewriteEmailSchema)
+    result, llm_call_info = chain(
+        REWRITE_EMAIL_PROMPT.format(
+            style=style,
+            draft=draft_text,
+        )
+    )
+    return result.rewritten_email, llm_call_info

openmail/assistants/summarize_attachments_for_email.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import looks_binary, safe_decode
+
+ATTACHMENT_SUMMARY_PROMPT = """
+You are an assistant that summarizes file attachments from an email.
+
+Instructions:
+- For each attachment, provide a concise summary (3-6 sentences).
+- Focus on key points, decisions, and any important data.
+- Do not copy large passages verbatim.
+- If the content is not meaningful (e.g. very short or empty), say so briefly.
+
+Below are the attachments with their content.
+
+Attachments:
+{attachments_context}
+"""
+
+
+class AttachmentSummarySchema(BaseModel):
+    filename: str = Field(description="Filename of the attachment.")
+    summary: str = Field(description="Concise summary of the attachment's contents.")
+
+
+class AttachmentSummariesSchema(BaseModel):
+    attachments: List[AttachmentSummarySchema] = Field(
+        description="List of summaries for each attachment."
+    )
+
+
+def _build_attachments_context(message: EmailMessage) -> str:
+    """
+    Build a text context representing all attachments.
+
+    Adjust attribute names here to match your actual attachment model.
+    """
+
+    attachments = message.attachments
+    parts: List[str] = []
+
+    for idx, att in enumerate(attachments, start=1):
+        filename = att.filename
+        # Try common attributes for text content
+        data = att.data
+        decoded = safe_decode(data)
+
+        if not decoded:
+            parts.append(
+                f"--- Attachment #{idx} ---\n"
+                f"Filename: {filename}\n"
+                f"Content: [non-text or empty bytes]\n"
+            )
+            continue
+
+        if looks_binary(decoded):
+            parts.append(
+                f"--- Attachment #{idx} ---\n"
+                f"Filename: {filename}\n"
+                f"Content: [binary data - not summarized]\n"
+            )
+            continue
+
+        if len(decoded) > 4000:
+            decoded = decoded[:4000] + "\n...[truncated]..."
+
+        parts.append(
+            f"--- Attachment #{idx} ---\n" f"Filename: {filename}\n" f"Content:\n{decoded}\n"
+        )
+
+    return "\n".join(parts)
+
+
+def llm_summarize_attachments_for_email(
+    message: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[Dict[str, str], dict[str, Any]]:
+    """
+    Summarize each attachment in an email.
+    """
+    attachments = message.attachments
+    if not attachments:
+        return {}, {}
+
+    attachments_context = _build_attachments_context(message)
+
+    chain = get_model(provider, model_name, AttachmentSummariesSchema)
+    result, llm_call_info = chain(
+        ATTACHMENT_SUMMARY_PROMPT.format(attachments_context=attachments_context)
+    )
+
+    summaries: Dict[str, str] = {att.filename: att.summary for att in result.attachments}
+    return summaries, llm_call_info

openmail/assistants/summarize_thread_emails.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, List, Sequence, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+THREAD_SUMMARY_PROMPT = """
+You are an assistant that summarizes email conversation threads.
+
+Instructions:
+- Read the entire thread carefully.
+- Provide a concise summary (5-10 sentences).
+- Focus on:
+  - Overall context and purpose of the thread.
+  - Key decisions that have been made.
+  - Open questions that still need answers.
+  - Action items and who is responsible for them (if specified).
+- Write in clear, professional language.
+- Do not include greetings or sign-offs.
+
+Email thread (oldest to newest):
+{thread_context}
+"""
+
+
+class ThreadSummarySchema(BaseModel):
+    summary: str = Field(
+        description="Concise summary of the email thread, including context, decisions, open questions, and action items."
+    )
+
+
+def llm_summarize_thread_emails(
+    messages: Sequence[EmailMessage],
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[str, dict[str, Any]]:
+    """
+    Summarize a sequence of emails representing a thread.
+    """
+
+    parts: List[str] = []
+    for idx, msg in enumerate(messages, start=1):
+        ctx = build_email_context(msg)
+        parts.append(f"--- Email #{idx} ---\n{ctx}\n")
+
+    thread_context = "\n".join(parts)
+
+    chain = get_model(provider, model_name, ThreadSummarySchema)
+    result, llm_call_info = chain(THREAD_SUMMARY_PROMPT.format(thread_context=thread_context))
+    return result.summary, llm_call_info

openmail/assistants/summary.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+EMAIL_SUMMARY_PROMPT = """
+You are an assistant that summarizes emails for a busy user.
+
+Instructions (follow all):
+- Summarize the email in 2-4 sentences.
+- Capture the main points, action items, and any dates/deadlines.
+- Do NOT include any meta commentary, just the summary text.
+
+Email context:
+{email_context}
+"""
+
+
+class EmailSummarySchema(BaseModel):
+    summary: str = Field(description="A concise summary of a single email.")
+
+
+def llm_summarize_single_email(
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[str, Dict[str, Any]]:
+    """
+    Generate a concise email reply using the LLM pipeline.
+    """
+    chain = get_model(provider, model_name, EmailSummarySchema)
+    email_context = build_email_context(msg)
+    result, llm_call_info = chain(
+        EMAIL_SUMMARY_PROMPT.format(
+            email_context=email_context,
+        )
+    )
+    return result.summary, llm_call_info

openmail/assistants/summary_multi.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+EMAIL_MULTI_SUMMARY_PROMPT = """
+You are helping a user triage multiple emails.
+
+You will see several emails, each labeled with a UID.
+
+Instructions (follow all):
+- Write ONE short paragraph.
+- Clearly state which emails are IMPORTANT or URGENT.
+- Briefly mention the other emails as less important.
+- When referring to an IMPORTANT email, you MUST mention its UID exactly
+  as 'UID=<number>' so the UI can link directly to it.
+- Keep the paragraph compact and easy to scan.
+
+Emails:
+{emails_block}
+"""
+
+
+class EmailMultiSummarySchema(BaseModel):
+    summary: str = Field(description="One paragraph summarizing and prioritizing multiple emails.")
+
+
+def llm_summarize_many_emails(
+    messages: Sequence[EmailMessage],
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[Optional[str], Dict[str, Any]]:
+    """
+    Generate a concise email reply using the LLM pipeline.
+    """
+    chain = get_model(provider, model_name, EmailMultiSummarySchema)
+
+    blocks: List[str] = []
+    for msg in messages:
+        email_context = build_email_context(msg)
+        blocks.append(email_context)
+
+    emails_block = "\n---\n".join(blocks)
+
+    result, llm_call_info = chain(
+        EMAIL_MULTI_SUMMARY_PROMPT.format(
+            emails_block=emails_block,
+        )
+    )
+
+    return result.summary, llm_call_info

openmail/assistants/translate_email.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+
+TRANSLATE_EMAIL_PROMPT = """
+You are a translation assistant.
+
+Instructions:
+- Translate the text into the target language.
+- Preserve tone and level of formality as much as reasonable.
+- Do not add explanations, comments, or notes—only output the translated text.
+- Keep formatting (line breaks, bullet points) where it makes sense.
+
+Target language: {target_language}
+{source_line}
+
+Text to translate:
+{text}
+"""
+
+
+class TranslateEmailSchema(BaseModel):
+    translated_text: str = Field(description="The translated text in the target language.")
+
+
+def llm_translate_email(
+    text: str,
+    *,
+    target_language: str,
+    source_language: Optional[str],
+    provider: str,
+    model_name: str,
+) -> Tuple[str, dict[str, Any]]:
+    """
+    Translate arbitrary text to a target language.
+    """
+    if source_language:
+        source_line = f"Source language: {source_language}"
+    else:
+        source_line = "Source language: auto-detect"
+
+    chain = get_model(provider, model_name, TranslateEmailSchema)
+    result, llm_call_info = chain(
+        TRANSLATE_EMAIL_PROMPT.format(
+            target_language=target_language,
+            source_line=source_line,
+            text=text,
+        )
+    )
+    return result.translated_text, llm_call_info

openmail/auth/__init__.py

@@ -0,0 +1,6 @@
+from openmail.auth.base import AuthContext, IMAPAuth, SMTPAuth
+from openmail.auth.no_auth import NoAuth
+from openmail.auth.oauth2 import OAuth2Auth
+from openmail.auth.password import PasswordAuth
+
+__all__ = ["SMTPAuth", "IMAPAuth", "AuthContext", "PasswordAuth", "OAuth2Auth", "NoAuth"]

openmail/auth/base.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """
+    Extra context an auth method may need.
+    (Keep this minimal; extend later.)
+    """
+
+    host: str
+    port: int
+    username: Optional[str] = None
+
+
+@runtime_checkable
+class SMTPAuth(Protocol):
+    """
+    Something that knows how to authenticate an smtplib.SMTP-like object.
+    """
+
+    def apply_smtp(self, server, ctx: AuthContext) -> None: ...
+
+
+@runtime_checkable
+class IMAPAuth(Protocol):
+    """
+    Something that knows how to authenticate an imaplib.IMAP4-like object.
+    """
+
+    def apply_imap(self, conn, ctx: AuthContext) -> None: ...

openmail/auth/no_auth.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from openmail.auth.base import AuthContext
+
+
+@dataclass(frozen=True)
+class NoAuth:
+    """
+    Represents 'no authentication required'. Useful for SMTP relays
+    or IMAP/SMTP servers that don't require login for this client.
+    """
+
+    def apply_smtp(self, server, ctx: AuthContext) -> None:
+        return
+
+    def apply_imap(self, conn, ctx: AuthContext) -> None:
+        return

openmail/auth/oauth2.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Callable
+
+from openmail.auth.base import AuthContext
+from openmail.errors import AuthError
+
+
+@dataclass(frozen=True)
+class OAuth2Auth:
+    """
+    XOAUTH2-based auth. You provide a function that returns a fresh access token.
+    - token_provider() -> access_token (string)
+    """
+
+    username: str
+    token_provider: Callable[..., str]
+
+    def _raw_xoauth2(self, access_token: str) -> str:
+        return f"user={self.username}\x01auth=Bearer {access_token}\x01\x01"
+
+    def apply_imap(self, conn, ctx: AuthContext) -> None:
+        try:
+            token = self.token_provider()
+            if not token:
+                raise AuthError("OAuth2 token provider returned empty token")
+
+            auth_bytes = self._raw_xoauth2(token).encode("utf-8")
+
+            def auth_cb(_):
+                return auth_bytes
+
+            typ, data = conn.authenticate("XOAUTH2", auth_cb)
+            if typ != "OK":
+                raise AuthError(f"IMAP XOAUTH2 auth failed (non-OK response: {typ}, {data})")
+        except Exception as e:
+            raise AuthError(f"IMAP XOAUTH2 auth failed: {e}") from e
+
+    def apply_smtp(self, server, ctx: AuthContext) -> None:
+        """
+        smtplib doesn't expose a single 'authenticate XOAUTH2' helper,
+        so we send AUTH XOAUTH2 with a base64-encoded initial response.
+        """
+        try:
+            token = self.token_provider()
+            if not token:
+                raise AuthError("OAuth2 token provider returned empty token")
+
+            raw = self._raw_xoauth2(token)
+            auth_b64 = base64.b64encode(raw.encode("utf-8")).decode("ascii")
+
+            code, resp = server.docmd("AUTH", "XOAUTH2 " + auth_b64)
+            if code != 235:
+                raise AuthError(f"SMTP XOAUTH2 auth failed: {code} {resp!r}")
+        except Exception as e:
+            raise AuthError(f"SMTP XOAUTH2 auth failed: {e}") from e