openmail 0.1.5__py3-none-any.whl

openmail/__init__.py

@@ -0,0 +1,6 @@
+from openmail.config import IMAPConfig, SMTPConfig
+from openmail.email_assistant import EmailAssistant
+from openmail.email_manager import EmailManager
+from openmail.email_query import EmailQuery
+
+__all__ = ["EmailManager", "SMTPConfig", "IMAPConfig", "EmailQuery", "EmailAssistant"]

openmail/assistants/__init__.py

@@ -0,0 +1,35 @@
+from openmail.assistants.classify_emails import llm_classify_emails
+from openmail.assistants.compose_email import llm_compose_email
+from openmail.assistants.detect_phishing_for_email import llm_detect_phishing_for_email
+from openmail.assistants.evaluate_sender_trust_for_email import llm_evaluate_sender_trust_for_email
+from openmail.assistants.extract_tasks_from_emails import llm_extract_tasks_from_emails
+from openmail.assistants.generate_follow_up_for_email import llm_generate_follow_up_for_email
+from openmail.assistants.natural_language_query import llm_easy_imap_query_from_nl
+from openmail.assistants.prioritize_emails import llm_prioritize_emails
+from openmail.assistants.reply import llm_concise_reply_for_email
+from openmail.assistants.reply_suggestions import llm_reply_suggestions_for_email
+from openmail.assistants.rewrite_email import llm_rewrite_email
+from openmail.assistants.summarize_attachments_for_email import llm_summarize_attachments_for_email
+from openmail.assistants.summarize_thread_emails import llm_summarize_thread_emails
+from openmail.assistants.summary import llm_summarize_single_email
+from openmail.assistants.summary_multi import llm_summarize_many_emails
+from openmail.assistants.translate_email import llm_translate_email
+
+__all__ = [
+    "llm_concise_reply_for_email",
+    "llm_summarize_single_email",
+    "llm_summarize_many_emails",
+    "llm_easy_imap_query_from_nl",
+    "llm_reply_suggestions_for_email",
+    "llm_classify_emails",
+    "llm_detect_phishing_for_email",
+    "llm_evaluate_sender_trust_for_email",
+    "llm_generate_follow_up_for_email",
+    "llm_prioritize_emails",
+    "llm_summarize_thread_emails",
+    "llm_compose_email",
+    "llm_rewrite_email",
+    "llm_translate_email",
+    "llm_extract_tasks_from_emails",
+    "llm_summarize_attachments_for_email",
+]

openmail/assistants/classify_emails.py

@@ -0,0 +1,83 @@
+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
+
+CLASSIFY_EMAILS_PROMPT = """
+You are an assistant that classifies emails into one of a small set of classes.
+
+Instructions:
+- You will be given multiple emails, each with an Email ID.
+- For each email, choose exactly ONE class from the allowed list.
+- For the output, return a list of objects, each with:
+  - id: the Email ID (copied exactly as given)
+  - label: the chosen class
+- Do not invent new class names; only use the provided classes.
+
+Allowed classes:
+{classes}
+
+Emails:
+{email_blocks}
+"""
+
+
+class EmailClassificationItem(BaseModel):
+    id: str = Field(description="Opaque ID that identifies one email.")
+    label: str = Field(description="Chosen class label for this email.")
+
+
+class EmailClassificationSchema(BaseModel):
+    items: List[EmailClassificationItem] = Field(
+        description=(
+            "List of classification results. Each item contains the email id "
+            "and the chosen class label."
+        )
+    )
+
+
+def llm_classify_emails(
+    messages: Sequence[EmailMessage],
+    *,
+    classes: Sequence[str],
+    provider: str,
+    model_name: str,
+) -> Tuple[Dict[EmailMessage, str], Dict[str, Any]]:
+    """
+    Classify a batch of emails into one of the provided classes.
+    """
+    if not messages:
+        return [], {}
+
+    chain = get_model(provider, model_name, EmailClassificationSchema)
+
+    id_list = [f"e{i + 1}" for i in range(len(messages))]
+    id_to_index = {id_: i for i, id_ in enumerate(id_list)}
+
+    classes_str = ", ".join(classes)
+
+    email_blocks = "\n\n".join(
+        f"Email ID: {email_id}\n{build_email_context(msg)}"
+        for email_id, msg in zip(id_list, messages)
+    )
+
+    result, llm_call_info = chain(
+        CLASSIFY_EMAILS_PROMPT.format(
+            classes=classes_str,
+            email_blocks=email_blocks,
+        )
+    )
+
+    # preserve order of input messages
+    labels: List[str] = [""] * len(messages)
+    for item in result.items:
+        idx = id_to_index.get(item.id)
+        if idx is not None:
+            labels[idx] = item.label
+
+    return labels, llm_call_info

openmail/assistants/compose_email.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+
+COMPOSE_EMAIL_PROMPT = """
+You are an assistant that drafts professional emails.
+
+Instructions:
+- Use clear, concise, professional language unless told otherwise.
+- Provide both a subject line and a body.
+- Do not include quotes or commentary about the email.
+- The body should be ready to send as-is (no placeholders like [NAME]).
+- Avoid overly flowery language.
+
+User instructions:
+{instructions}
+"""
+
+
+class ComposeEmailSchema(BaseModel):
+    subject: str = Field(description="Subject line for the email.")
+    body: str = Field(description="Full email body, ready to send.")
+
+
+def llm_compose_email(
+    instructions: str,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[str, str, dict[str, Any]]:
+    """
+    Compose a new email from natural-language instructions.
+    """
+    chain = get_model(provider, model_name, ComposeEmailSchema)
+    result, llm_call_info = chain(COMPOSE_EMAIL_PROMPT.format(instructions=instructions))
+
+    subject = result.subject.strip()
+    body = result.body.strip()
+    return subject, body, llm_call_info

openmail/assistants/detect_phishing_for_email.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+PHISHING_DETECTION_PROMPT = """
+You are a security assistant that determines whether an email is likely to be a phishing or scam attempt.
+
+Consider:
+- Suspicious links or requests (passwords, bank details, crypto, gift cards, etc.).
+- Urgency or threats designed to pressure the user.
+- Mismatched or spoofed sender names/domains.
+- Poor grammar or odd phrasing typical of scams.
+- Unsolicited attachments or requests to open files.
+
+Instructions:
+- Set is_phishing = true if the email is likely to be phishing or a scam.
+- Otherwise, set is_phishing = false.
+- Provide a confidence score between 0.0 and 1.0.
+- Briefly explain your reasoning referencing specific aspects of the email.
+
+Email context:
+{email_context}
+"""
+
+
+class PhishingDetectionSchema(BaseModel):
+    is_phishing: bool = Field(
+        description="True if the email is likely a phishing/scam attempt, else False."
+    )
+    confidence: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="Confidence in the phishing judgement, between 0.0 and 1.0.",
+    )
+    reasoning: str = Field(description="Short explanation for why the email is or is not phishing.")
+
+
+def llm_detect_phishing_for_email(
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[bool, dict[str, Any]]:
+    """
+    Detect whether an email is likely to be a phishing attempt.
+    """
+    chain = get_model(provider, model_name, PhishingDetectionSchema)
+    email_context = build_email_context(msg)
+
+    prompt = PHISHING_DETECTION_PROMPT.format(
+        email_context=email_context,
+    )
+
+    result, llm_call_info = chain(prompt)
+    return result.is_phishing, llm_call_info

openmail/assistants/evaluate_sender_trust_for_email.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+SENDER_TRUST_PROMPT = """
+You are an assistant that estimates how trustworthy the sender of an email appears.
+
+Consider:
+- Sender address and domain (well-known company, free email provider, random domain, etc.).
+- Consistency between display name and email address.
+- Professionalism and clarity of the writing.
+- Whether the content matches what you would expect from a legit sender.
+- Obvious red flags (phishing patterns, strange requests, etc.).
+
+Instructions:
+- Output a trust_score between 0.0 and 1.0:
+  - 1.0 = highly trustworthy (e.g., known and legitimate sender, no red flags).
+  - 0.0 = highly untrustworthy (e.g., obvious scam).
+- Base your judgement entirely on the email context provided.
+- Briefly explain your reasoning.
+
+Email context:
+{email_context}
+"""
+
+
+class SenderTrustSchema(BaseModel):
+    trust_score: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="How trustworthy the sender appears, between 0.0 (untrustworthy) and 1.0 (highly trustworthy).",
+    )
+    reasoning: str = Field(description="Short explanation for the chosen trust_score.")
+
+
+def llm_evaluate_sender_trust_for_email(
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[float, dict[str, Any]]:
+    """
+    Evaluate how trustworthy the sender appears based on the email.
+    """
+    chain = get_model(provider, model_name, SenderTrustSchema)
+    email_context = build_email_context(msg)
+
+    prompt = SENDER_TRUST_PROMPT.format(
+        email_context=email_context,
+    )
+
+    result, llm_call_info = chain(prompt)
+    return result.trust_score, llm_call_info

openmail/assistants/extract_tasks_from_emails.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage, Task
+from openmail.utils import build_email_context
+
+TASK_EXTRACTION_PROMPT = """
+You extract only important actionable tasks from one or more emails.
+
+Rules:
+- Be selective. Prefer missing minor tasks over adding noise.
+- Return at most 3 tasks per email.
+- Ignore emails without clearly actionable requests.
+- If no important tasks exist, return an empty list.
+- Do NOT invent tasks.
+
+Important tasks:
+- Explicit or implied requests for the recipient to act.
+- Deliverables, follow-ups, decisions, or deadlines.
+- Items with urgency or due dates.
+
+Exclude:
+- Promotions, marketing, newsletters.
+- FYI/announcements with no request.
+- Low-importance suggestions or optional ideas.
+- Automated notifications with no follow-up needed.
+
+Task fields:
+- Capture due dates and assignees if stated or clearly implied.
+- Set priority only if urgency is explicit.
+- Status is usually "todo".
+
+Email context:
+{email_context}
+"""
+
+
+class MetadataItem(BaseModel):
+    key: str = Field(description="Metadata key.")
+    value: str = Field(description="Metadata value.")
+
+
+class TaskSchema(BaseModel):
+    """
+    Generic task structure that can be reused across domains.
+    """
+
+    id: Optional[str] = Field(
+        default=None, description="A stable identifier if available; otherwise null."
+    )
+    title: str = Field(description="Short, human-readable label for the task.")
+    description: str = Field(description="Longer description with relevant context for the task.")
+    due_date: Optional[str] = Field(
+        default=None,
+        description="Due date or deadline in ISO 8601 format if specified; otherwise null.",
+    )
+    priority: Optional[str] = Field(
+        default=None, description='Priority such as "low", "medium", or "high", if inferable.'
+    )
+    status: Optional[str] = Field(
+        default=None, description='Status such as "todo", "in_progress", or "done"; usually "todo".'
+    )
+    assignee: Optional[str] = Field(
+        default=None, description="Person responsible for the task if known."
+    )
+    tags: List[str] = Field(
+        default_factory=list, description="List of keywords or labels for the task."
+    )
+    source_system: str = Field(description='Source system for the task, e.g. "email".')
+    source_id: Optional[str] = Field(
+        default=None, description="Identifier of the source record (e.g. message ID) if available."
+    )
+    source_link: Optional[str] = Field(
+        default=None, description="Deep link/URL to the source record if available."
+    )
+    metadata: List[MetadataItem] = Field(
+        default_factory=list, description="Additional domain-specific metadata as key-value pairs."
+    )
+
+
+class TaskExtractionSchema(BaseModel):
+    tasks: List[TaskSchema] = Field(description="List of tasks extracted from the email context.")
+
+
+def llm_extract_tasks_from_emails(
+    messages: Sequence[EmailMessage],
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[List[Task], dict[str, Any]]:
+    """
+    Extract tasks from one or more emails using a generic task structure.
+    """
+    parts: List[str] = []
+    for idx, msg in enumerate(messages, start=1):
+        ctx = build_email_context(msg)
+        parts.append(f"--- Email #{idx} ---\n{ctx}\n")
+
+    email_context = "\n".join(parts)
+
+    chain = get_model(provider, model_name, TaskExtractionSchema)
+    result, llm_call_info = chain(TASK_EXTRACTION_PROMPT.format(email_context=email_context))
+
+    tasks: List[Task] = []
+    for t in result.tasks:
+        tasks.append(
+            Task(
+                id=t.id,
+                title=t.title,
+                description=t.description,
+                due_date=t.due_date,
+                priority=t.priority,
+                status=t.status,
+                assignee=t.assignee,
+                tags=t.tags,
+                source_system=t.source_system,
+                source_id=t.source_id,
+                source_link=t.source_link,
+                metadata={item.key: item.value for item in t.metadata},
+            )
+        )
+    return tasks, llm_call_info

openmail/assistants/generate_follow_up_for_email.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from pydantic import BaseModel, Field
+
+from openmail.llm import get_model
+from openmail.models import EmailMessage
+from openmail.utils import build_email_context
+
+FOLLOW_UP_PROMPT = """
+You are an assistant that writes a polite, concise follow-up email.
+
+Context:
+- The user previously sent or received the email shown below.
+- They now want to send a follow-up because there has been no response or progress.
+
+Instructions:
+- Write a short, natural follow-up email body.
+- Keep it polite and professional.
+- Briefly reference the previous message.
+- Ask for an update or next steps.
+- Do NOT include a subject line.
+- Do NOT add salutations like "From:". Only include the email body content.
+
+Email context:
+{email_context}
+"""
+
+
+class FollowUpEmailSchema(BaseModel):
+    follow_up_body: str = Field(
+        description="A concise, polite follow-up email body text with no subject line."
+    )
+
+
+def llm_generate_follow_up_for_email(
+    msg: EmailMessage,
+    *,
+    provider: str,
+    model_name: str,
+) -> Tuple[str, dict[str, Any]]:
+    """
+    Generate a follow-up email body for a previous message.
+    """
+    chain = get_model(provider, model_name, FollowUpEmailSchema)
+    email_context = build_email_context(msg)
+
+    prompt = FOLLOW_UP_PROMPT.format(
+        email_context=email_context,
+    )
+
+    result, llm_call_info = chain(prompt)
+    return result.follow_up_body, llm_call_info