openmail 0.1.5__py3-none-any.whl

openmail/imap/query.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List
+
+
+def _imap_date(iso_yyyy_mm_dd: str) -> str:
+    dt = datetime.strptime(iso_yyyy_mm_dd, "%Y-%m-%d")
+    return dt.strftime("%d-%b-%Y")
+
+
+def _q(s: str) -> str:
+    """
+    Quote/escape a string for IMAP SEARCH.
+    """
+    s = s.replace("\\", "\\\\").replace('"', r"\"")
+    return f'"{s}"'
+
+
+@dataclass
+class IMAPQuery:
+    parts: List[str] = field(default_factory=list)
+
+    # --- basic fields ---
+    def from_(self, s: str) -> IMAPQuery:
+        self.parts += ["FROM", _q(s)]
+        return self
+
+    def to(self, s: str) -> IMAPQuery:
+        self.parts += ["TO", _q(s)]
+        return self
+
+    def cc(self, s: str) -> IMAPQuery:
+        self.parts += ["CC", _q(s)]
+        return self
+
+    def bcc(self, s: str) -> IMAPQuery:
+        self.parts += ["BCC", _q(s)]
+        return self
+
+    def subject(self, s: str) -> IMAPQuery:
+        self.parts += ["SUBJECT", _q(s)]
+        return self
+
+    def text(self, s: str) -> IMAPQuery:
+        """
+        Match in headers OR body text.
+        """
+        self.parts += ["TEXT", _q(s)]
+        return self
+
+    def body(self, s: str) -> IMAPQuery:
+        """
+        Match only in body text.
+        """
+        self.parts += ["BODY", _q(s)]
+        return self
+
+    def header(self, name: str, value: str) -> IMAPQuery:
+        self.parts += ["HEADER", _q(name), _q(value)]
+        return self
+
+    # --- date filters ---
+    def since(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["SINCE", _imap_date(iso_date)]
+        return self
+
+    def before(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["BEFORE", _imap_date(iso_date)]
+        return self
+
+    def on(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["ON", _imap_date(iso_date)]
+        return self
+
+    def sent_since(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["SENTSINCE", _imap_date(iso_date)]
+        return self
+
+    def sent_before(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["SENTBEFORE", _imap_date(iso_date)]
+        return self
+
+    def sent_on(self, iso_date: str) -> IMAPQuery:
+        self.parts += ["SENTON", _imap_date(iso_date)]
+        return self
+
+    # --- flags/status ---
+    def seen(self) -> IMAPQuery:
+        self.parts += ["SEEN"]
+        return self
+
+    def unseen(self) -> IMAPQuery:
+        self.parts += ["UNSEEN"]
+        return self
+
+    def answered(self) -> IMAPQuery:
+        self.parts += ["ANSWERED"]
+        return self
+
+    def unanswered(self) -> IMAPQuery:
+        self.parts += ["UNANSWERED"]
+        return self
+
+    def flagged(self) -> IMAPQuery:
+        self.parts += ["FLAGGED"]
+        return self
+
+    def unflagged(self) -> IMAPQuery:
+        self.parts += ["UNFLAGGED"]
+        return self
+
+    def deleted(self) -> IMAPQuery:
+        self.parts += ["DELETED"]
+        return self
+
+    def undeleted(self) -> IMAPQuery:
+        self.parts += ["UNDELETED"]
+        return self
+
+    def draft(self) -> IMAPQuery:
+        self.parts += ["DRAFT"]
+        return self
+
+    def undraft(self) -> IMAPQuery:
+        self.parts += ["UNDRAFT"]
+        return self
+
+    def recent(self) -> IMAPQuery:
+        self.parts += ["RECENT"]
+        return self
+
+    def new(self) -> IMAPQuery:
+        self.parts += ["NEW"]
+        return self
+
+    def old(self) -> IMAPQuery:
+        self.parts += ["OLD"]
+        return self
+
+    # --- size ---
+    def larger(self, n_bytes: int) -> IMAPQuery:
+        self.parts += ["LARGER", str(n_bytes)]
+        return self
+
+    def smaller(self, n_bytes: int) -> IMAPQuery:
+        self.parts += ["SMALLER", str(n_bytes)]
+        return self
+
+    # --- keyword ---
+    def keyword(self, name: str) -> IMAPQuery:
+        self.parts += ["KEYWORD", _q(name)]
+        return self
+
+    def unkeyword(self, name: str) -> IMAPQuery:
+        self.parts += ["UNKEYWORD", _q(name)]
+        return self
+
+    # --- UID search ---
+    def uid(self, *uids: int | str) -> IMAPQuery:
+        """
+        Accepts ranges ("1:100") or explicit UIDs (1,2,3)
+        """
+        joined = ",".join(str(u) for u in uids)
+        self.parts += ["UID", joined]
+        return self
+
+    # --- exclude fields ---
+    def _not(self, *tokens: str) -> IMAPQuery:
+        self.parts += ["NOT", *tokens]
+        return self
+
+    def exclude_from(self, s: str) -> IMAPQuery:
+        return self._not("FROM", _q(s))
+
+    def exclude_to(self, s: str) -> IMAPQuery:
+        return self._not("TO", _q(s))
+
+    def exclude_cc(self, s: str) -> IMAPQuery:
+        return self._not("CC", _q(s))
+
+    def exclude_bcc(self, s: str) -> IMAPQuery:
+        return self._not("BCC", _q(s))
+
+    def exclude_subject(self, s: str) -> IMAPQuery:
+        return self._not("SUBJECT", _q(s))
+
+    def exclude_header(self, name: str, value: str) -> IMAPQuery:
+        return self._not("HEADER", _q(name), _q(value))
+
+    def exclude_text(self, s: str) -> IMAPQuery:
+        return self._not("TEXT", _q(s))
+
+    def exclude_body(self, s: str) -> IMAPQuery:
+        return self._not("BODY", _q(s))
+
+    def or_(self, *queries: IMAPQuery) -> IMAPQuery:
+        qs = [q for q in (self, *queries) if q.parts]
+
+        if len(qs) < 2:
+            raise ValueError(
+                "or_ requires at least two non-empty IMAPQuery instances (including self)"
+            )
+
+        tokens: List[str] = list(qs[0].parts)
+
+        for q in qs[1:]:
+            right = list(q.parts)
+
+            tokens = ["OR", "("] + tokens + [")", "("] + right + [")"]
+
+        self.parts = tokens
+        return self
+
+    # --- composition helpers ---
+    def all(self) -> IMAPQuery:
+        self.parts += ["ALL"]
+        return self
+
+    def raw(self, *tokens: str) -> IMAPQuery:
+        """
+        Append raw tokens for advanced users, e.g. raw("OR", 'FROM "a"', 'FROM "b"')
+        """
+        self.parts += list(tokens)
+        return self
+
+    def build(self) -> str:
+        if not self.parts:
+            return "ALL"
+        s = " ".join(self.parts)
+        s = s.replace("( ", "(").replace(" )", ")")
+        return s

openmail/llm/__init__.py

@@ -0,0 +1,3 @@
+from openmail.llm.model import get_model
+
+__all__ = ["get_model"]

openmail/llm/claude.py

@@ -0,0 +1,35 @@
+from typing import Type
+
+from langchain_anthropic import ChatAnthropic
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from pydantic import BaseModel
+
+
+def get_claude(
+    model_name: str,
+    pydantic_model: Type[BaseModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+
+    base_llm = ChatAnthropic(
+        model=model_name,
+        temperature=temperature,
+        timeout=timeout,
+    )
+
+    llm_structured = base_llm.with_structured_output(pydantic_model)
+
+    base_prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Return ONLY valid JSON that matches the required schema. No extra text."),
+            MessagesPlaceholder("messages"),
+        ]
+    )
+
+    chain = base_prompt | llm_structured
+
+    if chain is None:
+        raise RuntimeError("LLM not available for the given model_name")
+
+    return chain

openmail/llm/costs.py

@@ -0,0 +1,108 @@
+from typing import Dict
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.outputs import LLMResult
+
+OPENAI_PRICES_PER_1M: Dict[str, Dict[str, float]] = {
+    "gpt-5-mini": {"input": 0.25, "cached_input": 0.025, "output": 2.00},
+    "gpt-5-nano": {"input": 0.05, "cached_input": 0.005, "output": 0.40},
+    "gpt-5.2": {"input": 1.75, "cached_input": 0.175, "output": 14.00},
+    "gpt-4o": {"input": 2.50, "cached_input": 1.25, "output": 10.00},
+    "gpt-4o-mini": {"input": 0.15, "cached_input": 0.075, "output": 0.60},
+}
+
+XAI_PRICES_PER_1M: Dict[str, Dict[str, float]] = {
+    "grok-4-1-fast-reasoning": {"input": 0.20, "cached_input": 0.05, "output": 0.50},
+    "grok-4-1-fast-non-reasoning": {"input": 0.20, "cached_input": 0.05, "output": 0.50},
+    "grok-4": {"input": 3.00, "cached_input": 0.75, "output": 15.00},
+    "grok-4-fast-reasoning": {"input": 0.20, "cached_input": 0.05, "output": 0.50},
+    "grok-4-fast-non-reasoning": {"input": 0.20, "cached_input": 0.05, "output": 0.50},
+    "grok-3-mini": {"input": 0.30, "cached_input": 0.075, "output": 0.50},
+    "grok-3": {"input": 3.00, "cached_input": 0.75, "output": 15.00},
+}
+GROQ_PRICES_PER_1M: Dict[str, Dict[str, float]] = {
+    "openai/gpt-oss-20b": {"input": 0.075, "cached_input": 0.037, "output": 0.30},
+    "openai/gpt-oss-120b": {"input": 0.15, "cached_input": 0.075, "output": 0.60},
+    "moonshotai/kimi-k2-instruct-0905": {"input": 1.00, "cached_input": 0.50, "output": 3.00},
+    "meta-llama/llama-4-scout-17b-16e-instruct": {
+        "input": 0.11,
+        "cached_input": 0.00,
+        "output": 0.34,
+    },
+    "meta-llama/llama-4-maverick-17b-128e-instruct": {
+        "input": 0.20,
+        "cached_input": 0.00,
+        "output": 0.60,
+    },
+    "qwen/qwen3-32b": {"input": 0.29, "cached_input": 0.00, "output": 0.59},
+    "llama-3.1-8b-instant": {"input": 0.05, "cached_input": 0.00, "output": 0.08},
+}
+
+GEMINI_PRICES_PER_1M: Dict[str, Dict[str, float]] = {
+    "gemini-3-flash-preview": {"input": 0.50, "cached_input": 0.05, "output": 3.00},
+    "gemini-2.5-flash": {"input": 0.30, "cached_input": 0.03, "output": 2.50},
+    "gemini-2.5-flash-lite": {"input": 0.10, "cached_input": 0.01, "output": 0.40},
+}
+
+CLAUDE_PRICES_PER_1M: Dict[str, Dict[str, float]] = {
+    "claude-opus-4.5": {"input": 5.00, "cached_input": 0.50, "output": 25.00},
+    "claude-opus-4.1": {"input": 15.00, "cached_input": 1.50, "output": 75.00},
+    "claude-opus-4": {"input": 15.00, "cached_input": 1.50, "output": 75.00},
+    "claude-sonnet-4.5": {"input": 3.00, "cached_input": 0.30, "output": 15.00},
+    "claude-sonnet-4": {"input": 3.00, "cached_input": 0.30, "output": 15.00},
+    "claude-haiku-4.5": {"input": 1.00, "cached_input": 0.10, "output": 5.00},
+    "claude-haiku-3.5": {"input": 0.80, "cached_input": 0.08, "output": 4.00},
+    "claude-haiku-3": {"input": 0.25, "cached_input": 0.03, "output": 1.25},
+}
+
+
+class TokenUsageCallback(BaseCallbackHandler):
+    """Collect token usage from a single LLM call."""
+
+    def __init__(self) -> None:
+        self.prompt_tokens = 0
+        self.completion_tokens = 0
+        self.total_tokens = 0
+        self.cached_prompt_tokens = 0
+
+    def on_llm_end(self, response: LLMResult, **kwargs) -> None:
+
+        usage = (response.llm_output or {}).get("token_usage")
+        if usage:
+            self.prompt_tokens += usage.get("prompt_tokens", 0)
+            self.completion_tokens += usage.get("completion_tokens", 0)
+            self.total_tokens += usage.get("total_tokens", 0)
+
+            prompt_details = usage.get("prompt_tokens_details") or {}
+            self.cached_prompt_tokens += prompt_details.get("cached_tokens", 0)
+            return
+
+
+def _lookup_price(provider: str, model_name: str) -> Dict[str, float]:
+    if provider == "openai":
+        return OPENAI_PRICES_PER_1M[model_name]
+    if provider == "gemini":
+        return GEMINI_PRICES_PER_1M[model_name]
+    if provider == "xai":
+        return XAI_PRICES_PER_1M[model_name]
+    if provider == "groq":
+        return GROQ_PRICES_PER_1M[model_name]
+    if provider == "claude":
+        return CLAUDE_PRICES_PER_1M[model_name]
+
+    return {"input": 0.0, "cached_input": 0.0, "output": 0.0}
+
+
+def compute_cost_usd(
+    provider: str,
+    model_name: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    cached_prompt_tokens: int = 0,
+) -> float:
+    prices = _lookup_price(provider, model_name)
+    return (
+        ((prompt_tokens - cached_prompt_tokens) / 1000000.0) * prices["input"]
+        + (cached_prompt_tokens / 1000000.0) * prices["cached_input"]
+        + (completion_tokens / 1000000.0) * prices["output"]
+    )

openmail/llm/gemini.py

@@ -0,0 +1,34 @@
+from typing import Type
+
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_google_genai import ChatGoogleGenerativeAI
+from pydantic import BaseModel
+
+
+def get_gemini(
+    model_name: str,
+    pydantic_model: Type[BaseModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+
+    base_llm = ChatGoogleGenerativeAI(
+        model=model_name,
+        temperature=temperature,
+        timeout=timeout,
+        convert_system_message_to_human=True,
+    )
+
+    llm_structured = base_llm.with_structured_output(pydantic_model)
+    base_prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Return ONLY valid JSON that matches the required schema. No extra text."),
+            MessagesPlaceholder("messages"),
+        ]
+    )
+    chain = base_prompt | llm_structured
+
+    if chain is None:
+        raise RuntimeError("LLM not available for the given model_name")
+
+    return chain

openmail/llm/gpt.py

@@ -0,0 +1,33 @@
+from typing import Type
+
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_openai import ChatOpenAI
+from pydantic import BaseModel
+
+
+def get_openai(
+    model_name: str,
+    pydantic_model: Type[BaseModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+
+    base_llm = ChatOpenAI(
+        model=model_name,
+        temperature=temperature,
+        timeout=timeout,
+    )
+
+    llm_structured = base_llm.with_structured_output(pydantic_model)
+    base_prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Return ONLY valid JSON that matches the required schema. No extra text."),
+            MessagesPlaceholder("messages"),
+        ]
+    )
+    chain = base_prompt | llm_structured
+
+    if chain is None:
+        raise RuntimeError("LLM not available for the given model_name")
+
+    return chain

openmail/llm/groq.py

@@ -0,0 +1,36 @@
+from typing import Type
+
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_groq import ChatGroq
+from pydantic import BaseModel
+
+
+def get_groq(
+    model_name: str,
+    pydantic_model: Type[BaseModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+
+    base_llm = ChatGroq(
+        model=model_name,
+        temperature=temperature,
+        timeout=timeout,
+    )
+
+    llm_structured = base_llm.with_structured_output(
+        pydantic_model,
+        method="function_calling",
+    )
+    base_prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Return ONLY valid JSON that matches the required schema. No extra text."),
+            MessagesPlaceholder("messages"),
+        ]
+    )
+    chain = base_prompt | llm_structured
+
+    if chain is None:
+        raise RuntimeError("LLM not available for the given model_name")
+
+    return chain

openmail/llm/model.py

@@ -0,0 +1,126 @@
+import time
+from functools import lru_cache
+from json import JSONDecodeError
+from random import random
+from time import sleep
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type, TypeVar
+
+from langchain_core.exceptions import OutputParserException
+from openai import APIConnectionError, APITimeoutError, RateLimitError
+from pydantic import BaseModel, ValidationError
+
+from openmail.llm.claude import get_claude
+from openmail.llm.costs import TokenUsageCallback, compute_cost_usd
+from openmail.llm.gemini import get_gemini
+from openmail.llm.gpt import get_openai
+from openmail.llm.groq import get_groq
+from openmail.llm.xai import get_xai
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+@lru_cache(maxsize=None)
+def _get_base_llm(
+    provider: str,
+    model_name: str,
+    pydantic_model: Type[TModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+    if provider == "openai":
+        return get_openai(model_name, pydantic_model, temperature, timeout)
+    if provider == "gemini":
+        return get_gemini(model_name, pydantic_model, temperature, timeout)
+    if provider == "xai":
+        return get_xai(model_name, pydantic_model, temperature, timeout)
+    if provider == "groq":
+        return get_groq(model_name, pydantic_model, temperature, timeout)
+    if provider == "claude":
+        return get_claude(model_name, pydantic_model, temperature, timeout)
+
+    raise RuntimeError("LLM not available for the given model_name")
+
+
+def get_model(
+    provider: str,
+    model_name: str,
+    pydantic_model: Type[TModel],
+    temperature: float = 0.1,
+    retries: int = 5,  # -1 for infinite retries
+    base_delay: float = 1.5,
+    max_delay: float = 30.0,
+    timeout: int = 120,
+    all_fail_raise: bool = True,
+) -> Callable[[str], Tuple[TModel, Dict[str, Any]]]:
+
+    chain = _get_base_llm(provider, model_name, pydantic_model, temperature, timeout)
+
+    TRANSIENT_EXC = (APIConnectionError, APITimeoutError, RateLimitError)
+    PARSE_EXC = (JSONDecodeError, OutputParserException, ValidationError)
+
+    history: List[Dict[str, str]] = []
+
+    def run(prompt_text: str) -> Tuple[TModel, Dict[str, Any]]:
+        nonlocal history
+        infinite = retries == -1
+        max_tries = float("inf") if infinite else max(1, retries)
+        delay = base_delay
+        last_exc: Optional[BaseException] = None
+
+        attempt = 0
+        while attempt < max_tries:
+            try:
+                messages = history + [
+                    {"role": "user", "content": prompt_text},
+                ]
+
+                usage_cb = TokenUsageCallback()
+                t0 = time.perf_counter()
+                out = chain.invoke(
+                    {"messages": messages},
+                    config={"callbacks": [usage_cb]},
+                )
+                t1 = time.perf_counter()
+
+                model_obj = (
+                    out if isinstance(out, BaseModel) else pydantic_model.model_validate(out)
+                )
+                out_dict = model_obj.model_dump()
+
+                history = messages + [{"role": "assistant", "content": model_obj.model_dump_json()}]
+
+                cost_usd = compute_cost_usd(
+                    provider,
+                    model_name,
+                    prompt_tokens=usage_cb.prompt_tokens,
+                    completion_tokens=usage_cb.completion_tokens,
+                    cached_prompt_tokens=usage_cb.cached_prompt_tokens,
+                )
+                llm_call_info = {
+                    "model": model_name,
+                    "prompt": prompt_text,
+                    "response": out_dict,
+                    "call_time": t1 - t0,
+                    "timestamp": time.strftime("%m/%d/%Y_%H:%M:%S"),
+                    "prompt_tokens": usage_cb.prompt_tokens,
+                    "completion_tokens": usage_cb.completion_tokens,
+                    "cached_prompt_tokens": usage_cb.cached_prompt_tokens,
+                    "cost_usd": cost_usd,
+                }
+
+                return model_obj, llm_call_info
+
+            except (*TRANSIENT_EXC, *PARSE_EXC) as e:
+                last_exc = e
+            except Exception as e:
+                last_exc = e
+
+            attempt += 1
+            if not infinite and attempt >= max_tries:
+                if all_fail_raise and last_exc is not None:
+                    raise last_exc
+
+            sleep(delay + random() * 0.5)
+            delay = min(delay * 2, max_delay)
+
+    return run

openmail/llm/xai.py

@@ -0,0 +1,35 @@
+from typing import Type
+
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_xai import ChatXAI
+from pydantic import BaseModel
+
+
+def get_xai(
+    model_name: str,
+    pydantic_model: Type[BaseModel],
+    temperature: float = 0.1,
+    timeout: int = 120,
+):
+
+    base_llm = ChatXAI(
+        model=model_name,
+        temperature=temperature,
+        timeout=timeout,
+    )
+
+    llm_structured = base_llm.with_structured_output(pydantic_model)
+
+    base_prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Return ONLY valid JSON that matches the required schema. No extra text."),
+            MessagesPlaceholder("messages"),
+        ]
+    )
+
+    chain = base_prompt | llm_structured
+
+    if chain is None:
+        raise RuntimeError("LLM not available for the given model_name")
+
+    return chain

openmail/logger.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import logging
+
+LOGGER_NAME = "email_manager"
+
+
+def get_logger(name: str = LOGGER_NAME) -> logging.Logger:
+    return logging.getLogger(name)
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    logger = get_logger()
+    if logger.handlers:
+        return
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s %(levelname)s [%(name)s] %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(level)

openmail/models/__init__.py

@@ -0,0 +1,20 @@
+from openmail.models.attachment import Attachment, AttachmentMeta
+from openmail.models.message import EmailAddress, EmailMessage, EmailOverview
+from openmail.models.subscription import (
+    UnsubscribeActionResult,
+    UnsubscribeCandidate,
+    UnsubscribeMethod,
+)
+from openmail.models.task import Task
+
+__all__ = [
+    "EmailAddress",
+    "EmailMessage",
+    "EmailOverview",
+    "AttachmentMeta",
+    "Attachment",
+    "UnsubscribeMethod",
+    "UnsubscribeCandidate",
+    "UnsubscribeActionResult",
+    "Task",
+]