nornweave 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

nornweave/adapters/resend.py

@@ -253,38 +253,88 @@ class ResendAdapter(EmailProvider):
             result: dict[str, Any] = response.json()
             return result
 
-    async def fetch_attachment_content(self, email_id: str, attachment_id: str) -> bytes:
+    async def fetch_attachment_content(
+        self, email_id: str, attachment_id: str, *, inbound: bool = True
+    ) -> bytes:
         """Fetch attachment content from Resend API.
 
+        The Resend API returns attachment metadata with a download_url.
+        This method fetches the metadata, then downloads the actual content.
+
+        See:
+        - Inbound: https://resend.com/docs/api-reference/emails/retrieve-received-email-attachment
+        - Outbound: https://resend.com/docs/api-reference/emails/retrieve-email-attachment
+
         Args:
             email_id: Resend email ID
             attachment_id: Attachment ID from webhook/email data
+            inbound: If True, use receiving endpoint; if False, use sending endpoint
 
         Returns:
             Attachment binary content
         """
-        url = f"{self._api_url}/emails/receiving/{email_id}/attachments/{attachment_id}"
+        # Step 1: Get attachment metadata (contains download_url)
+        # Use different endpoints for inbound vs outbound emails
+        if inbound:
+            metadata_url = (
+                f"{self._api_url}/emails/receiving/{email_id}/attachments/{attachment_id}"
+            )
+        else:
+            metadata_url = f"{self._api_url}/emails/{email_id}/attachments/{attachment_id}"
 
-        logger.debug("Fetching attachment %s from email %s", attachment_id, email_id)
+        logger.debug("Fetching attachment metadata %s from email %s", attachment_id, email_id)
 
         async with httpx.AsyncClient() as client:
             response = await client.get(
-                url,
+                metadata_url,
                 headers={
                     "Authorization": f"Bearer {self._api_key}",
                 },
-                timeout=60.0,
+                timeout=30.0,
             )
 
             if response.status_code != 200:
                 logger.error(
-                    "Resend API error fetching attachment: %s - %s",
+                    "Resend API error fetching attachment metadata: %s - %s",
                     response.status_code,
                     response.text,
                 )
                 response.raise_for_status()
 
-            return response.content
+            metadata = response.json()
+            download_url = metadata.get("download_url")
+
+            if not download_url:
+                raise ValueError(f"No download_url in attachment metadata: {metadata}")
+
+            logger.debug(
+                "Got attachment metadata: filename=%s, size=%s, downloading from %s",
+                metadata.get("filename"),
+                metadata.get("size"),
+                download_url[:50] + "..." if len(download_url) > 50 else download_url,
+            )
+
+            # Step 2: Download actual content from the CDN URL
+            content_response = await client.get(
+                download_url,
+                timeout=60.0,
+                follow_redirects=True,
+            )
+
+            if content_response.status_code != 200:
+                logger.error(
+                    "Error downloading attachment content: %s - %s",
+                    content_response.status_code,
+                    content_response.text[:200] if content_response.text else "No content",
+                )
+                content_response.raise_for_status()
+
+            logger.debug(
+                "Downloaded attachment content: %d bytes",
+                len(content_response.content),
+            )
+
+            return content_response.content
 
     def parse_inbound_webhook(self, payload: dict[str, Any]) -> InboundMessage:
         """Parse Resend inbound webhook payload into standardized InboundMessage.

nornweave/core/config.py

@@ -3,7 +3,7 @@
 from functools import lru_cache
 from typing import Literal
 
-from pydantic import Field
+from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -146,6 +146,44 @@ class Settings(BaseSettings):
         description="Maximum number of attachments per message",
     )
 
+    # -------------------------------------------------------------------------
+    # LLM Thread Summarization Configuration
+    # -------------------------------------------------------------------------
+    llm_provider: Literal["openai", "anthropic", "gemini"] | None = Field(
+        default=None,
+        alias="LLM_PROVIDER",
+        description="LLM provider for thread summarization. None = feature disabled.",
+    )
+    llm_api_key: str = Field(
+        default="",
+        alias="LLM_API_KEY",
+        description="API key for the selected LLM provider",
+    )
+    llm_model: str = Field(
+        default="",
+        alias="LLM_MODEL",
+        description="Model override (auto-selected per provider if empty)",
+    )
+    llm_summary_prompt: str = Field(
+        default=(
+            "You are an email thread summarizer. Given a chronological email conversation, "
+            "produce a concise summary that captures:\n"
+            "- Key topics discussed\n"
+            "- Decisions made or actions agreed upon\n"
+            "- Open questions or pending items\n"
+            "- Current status of the conversation\n\n"
+            "Keep the summary under 300 words. Use bullet points for clarity.\n"
+            "Do not include greetings, sign-offs, or meta-commentary."
+        ),
+        alias="LLM_SUMMARY_PROMPT",
+        description="System prompt for thread summarization",
+    )
+    llm_daily_token_limit: int = Field(
+        default=1_000_000,
+        alias="LLM_DAILY_TOKEN_LIMIT",
+        description="Max tokens per day for summarization (0 = unlimited)",
+    )
+
     # -------------------------------------------------------------------------
     # Content Extraction Configuration (Talon)
     # -------------------------------------------------------------------------
@@ -165,6 +203,17 @@ class Settings(BaseSettings):
         description="Return original content if extraction fails",
     )
 
+    @model_validator(mode="after")
+    def validate_llm_config(self) -> Settings:
+        """Validate LLM configuration: API key is required when provider is set."""
+        if self.llm_provider is not None and not self.llm_api_key:
+            msg = (
+                f"LLM_API_KEY is required when LLM_PROVIDER is set to '{self.llm_provider}'. "
+                "Set LLM_API_KEY in your environment or .env file."
+            )
+            raise ValueError(msg)
+        return self
+
 
 @lru_cache
 def get_settings() -> Settings:

nornweave/core/interfaces.py

@@ -2,7 +2,7 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import date, datetime
 from typing import TYPE_CHECKING, Any
 
 from nornweave.models.attachment import AttachmentDisposition, SendAttachment
@@ -252,6 +252,31 @@ class StorageInterface(ABC):
         """Search messages by content (ILIKE/LIKE on content_clean and content_raw)."""
         ...
 
+    @abstractmethod
+    async def search_messages_advanced(
+        self,
+        *,
+        inbox_id: str | None = None,
+        thread_id: str | None = None,
+        query: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> tuple[list[Message], int]:
+        """
+        Search messages with flexible filters.
+
+        Args:
+            inbox_id: Filter by inbox (optional)
+            thread_id: Filter by thread (optional)
+            query: Text search across subject, text, from_address, attachment filenames
+            limit: Maximum results to return
+            offset: Pagination offset
+
+        Returns:
+            Tuple of (messages, total_count)
+        """
+        ...
+
     # -------------------------------------------------------------------------
     # Event methods (Phase 3 webhooks)
     # -------------------------------------------------------------------------
@@ -291,6 +316,8 @@ class StorageInterface(ABC):
         content_id: str | None = None,
         storage_path: str | None = None,
         storage_backend: str | None = None,
+        content_hash: str | None = None,
+        content: bytes | None = None,
     ) -> str:
         """Create attachment record. Returns attachment ID."""
         ...
@@ -305,6 +332,28 @@ class StorageInterface(ABC):
         """List attachments for a message."""
         ...
 
+    @abstractmethod
+    async def list_attachments_for_thread(
+        self,
+        thread_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """List attachments for all messages in a thread."""
+        ...
+
+    @abstractmethod
+    async def list_attachments_for_inbox(
+        self,
+        inbox_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """List attachments for all messages in an inbox."""
+        ...
+
     @abstractmethod
     async def delete_attachment(self, attachment_id: str) -> bool:
         """Delete attachment. Returns True if deleted."""
@@ -331,6 +380,19 @@ class StorageInterface(ABC):
         """Get thread by normalized subject within time window (for subject-based threading)."""
         ...
 
+    # -------------------------------------------------------------------------
+    # LLM Token Usage methods
+    # -------------------------------------------------------------------------
+    @abstractmethod
+    async def get_token_usage(self, usage_date: date) -> int:
+        """Get total tokens used for a given date. Returns 0 if no record exists."""
+        ...
+
+    @abstractmethod
+    async def record_token_usage(self, usage_date: date, tokens: int) -> None:
+        """Record token usage for a given date. Creates or increments the daily counter."""
+        ...
+
 
 class EmailProvider(ABC):
     """Abstract email provider (BYOP). Implementations: Mailgun, SES, SendGrid, Resend."""

nornweave/huginn/client.py

@@ -173,25 +173,36 @@ class NornWeaveClient:
 
     async def list_messages(
         self,
-        inbox_id: str,
+        inbox_id: str | None = None,
+        thread_id: str | None = None,
+        q: str | None = None,
         limit: int = 50,
         offset: int = 0,
     ) -> dict[str, Any]:
-        """List messages for an inbox.
+        """List and search messages with flexible filters.
+
+        At least one of inbox_id or thread_id must be provided.
 
         Args:
-            inbox_id: The inbox ID.
+            inbox_id: Filter by inbox ID (optional).
+            thread_id: Filter by thread ID (optional).
+            q: Text search query (optional).
             limit: Maximum number of messages to return.
             offset: Number of messages to skip.
 
         Returns:
-            List response with messages.
+            List response with messages, count, and total.
         """
         client = await self._get_client()
-        response = await client.get(
-            "/v1/messages",
-            params={"inbox_id": inbox_id, "limit": limit, "offset": offset},
-        )
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if inbox_id:
+            params["inbox_id"] = inbox_id
+        if thread_id:
+            params["thread_id"] = thread_id
+        if q:
+            params["q"] = q
+
+        response = await client.get("/v1/messages", params=params)
         response.raise_for_status()
         return cast("dict[str, Any]", response.json())
 
@@ -294,3 +305,121 @@ class NornWeaveClient:
         if not messages:
             return None
         return cast("dict[str, Any]", messages[-1])
+
+    # -------------------------------------------------------------------------
+    # Attachment Operations
+    # -------------------------------------------------------------------------
+
+    async def list_attachments(
+        self,
+        message_id: str | None = None,
+        thread_id: str | None = None,
+        inbox_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List attachments filtered by message, thread, or inbox.
+
+        Args:
+            message_id: Filter by message ID.
+            thread_id: Filter by thread ID.
+            inbox_id: Filter by inbox ID.
+            limit: Maximum number of attachments to return.
+            offset: Number of attachments to skip.
+
+        Returns:
+            List response with attachment metadata.
+        """
+        client = await self._get_client()
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if message_id:
+            params["message_id"] = message_id
+        elif thread_id:
+            params["thread_id"] = thread_id
+        elif inbox_id:
+            params["inbox_id"] = inbox_id
+
+        response = await client.get("/v1/attachments", params=params)
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def get_attachment(self, attachment_id: str) -> dict[str, Any]:
+        """Get attachment metadata.
+
+        Args:
+            attachment_id: The attachment ID.
+
+        Returns:
+            Attachment metadata with download_url.
+        """
+        client = await self._get_client()
+        response = await client.get(f"/v1/attachments/{attachment_id}")
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def get_attachment_content(
+        self,
+        attachment_id: str,
+        response_format: str = "base64",
+    ) -> dict[str, Any]:
+        """Get attachment content.
+
+        Args:
+            attachment_id: The attachment ID.
+            response_format: Response format - "binary" or "base64" (default: base64).
+
+        Returns:
+            For base64: {"content": "...", "content_type": "...", "filename": "..."}
+            For binary: raw bytes (handled by httpx)
+        """
+        client = await self._get_client()
+        response = await client.get(
+            f"/v1/attachments/{attachment_id}/content",
+            params={"format": response_format},
+        )
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())
+
+    async def send_message_with_attachments(
+        self,
+        inbox_id: str,
+        to: list[str],
+        subject: str,
+        body: str,
+        attachments: list[dict[str, str]],
+        reply_to_thread_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Send an outbound message with attachments.
+
+        Args:
+            inbox_id: The inbox ID to send from.
+            to: List of recipient email addresses.
+            subject: Email subject.
+            body: Markdown body content.
+            attachments: List of attachment dicts with filename, content_type, content (base64).
+            reply_to_thread_id: Thread ID if this is a reply.
+
+        Returns:
+            Send response with message_id, thread_id, status.
+        """
+        client = await self._get_client()
+        payload: dict[str, Any] = {
+            "inbox_id": inbox_id,
+            "to": to,
+            "subject": subject,
+            "body": body,
+            "attachments": [
+                {
+                    "filename": att["filename"],
+                    "content_type": att["content_type"],
+                    "content_base64": att["content"],
+                }
+                for att in attachments
+            ],
+        }
+        if reply_to_thread_id:
+            payload["reply_to_thread_id"] = reply_to_thread_id
+
+        response = await client.post("/v1/messages", json=payload)
+        response.raise_for_status()
+        return cast("dict[str, Any]", response.json())

nornweave/huginn/resources.py

@@ -52,6 +52,7 @@ async def get_recent_threads(client: NornWeaveClient, inbox_id: str) -> str:
                     "last_message_at": thread.get("last_message_at"),
                     "message_count": message_count,
                     "participants": participants,
+                    "summary": thread.get("summary"),
                 }
             )
 
@@ -114,6 +115,14 @@ def format_thread_markdown(thread: dict[str, Any]) -> str:
     lines.append(f"## Thread: {subject}")
     lines.append("")
 
+    # Include summary if available
+    summary = thread.get("summary")
+    if summary:
+        lines.append("## Summary")
+        lines.append("")
+        lines.append(summary)
+        lines.append("")
+
     messages = thread.get("messages", [])
     if not messages:
         lines.append("*No messages in this thread.*")

nornweave/huginn/server.py

@@ -15,12 +15,21 @@ from fastmcp import FastMCP
 
 from nornweave.huginn.client import NornWeaveClient
 from nornweave.huginn.resources import get_recent_threads, get_thread_content
-from nornweave.muninn.tools import create_inbox, search_email, send_email, wait_for_reply
+from nornweave.muninn.tools import (
+    create_inbox,
+    get_attachment_content,
+    list_attachments,
+    list_messages,
+    search_email,
+    send_email,
+    send_email_with_attachments,
+    wait_for_reply,
+)
 
 # Create the FastMCP server
 mcp = FastMCP(
     name="nornweave",
-    version="0.1.2",
+    version="0.1.3",
     instructions="Email capabilities for AI agents - create inboxes, send emails, search messages",
 )
 
@@ -115,21 +124,66 @@ async def tool_send_email(
 
 
 @mcp.tool()
-async def tool_search_email(query: str, inbox_id: str, limit: int = 10) -> dict[str, Any]:
-    """Search for emails.
+async def tool_search_email(
+    query: str,
+    inbox_id: str | None = None,
+    thread_id: str | None = None,
+    limit: int = 10,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """Search for emails with flexible filters.
 
-    Find relevant messages in an inbox by query text.
+    Find relevant messages by query text. At least one of inbox_id or thread_id must be provided.
 
     Args:
-        query: Search query (e.g., "invoice", "meeting request")
-        inbox_id: Inbox to search in
+        query: Search query (searches subject, body, sender, attachment filenames)
+        inbox_id: Filter by inbox ID (optional)
+        thread_id: Filter by thread ID (optional)
         limit: Maximum number of results (default: 10, max: 100)
+        offset: Pagination offset (default: 0)
 
     Returns:
-        Search results with matching messages containing id, thread_id, content, created_at.
+        Search results with matching messages containing full email metadata.
     """
     client = _get_client()
-    return await search_email(client, query=query, inbox_id=inbox_id, limit=min(limit, 100))
+    return await search_email(
+        client,
+        query=query,
+        inbox_id=inbox_id,
+        thread_id=thread_id,
+        limit=min(limit, 100),
+        offset=offset,
+    )
+
+
+@mcp.tool()
+async def tool_list_messages(
+    inbox_id: str | None = None,
+    thread_id: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """List messages with flexible filters.
+
+    List messages from an inbox or thread. At least one of inbox_id or thread_id must be provided.
+
+    Args:
+        inbox_id: Filter by inbox ID (optional)
+        thread_id: Filter by thread ID (optional)
+        limit: Maximum number of results (default: 50, max: 100)
+        offset: Pagination offset (default: 0)
+
+    Returns:
+        List of messages with full email metadata including subject, from_address, to_addresses, text, etc.
+    """
+    client = _get_client()
+    return await list_messages(
+        client,
+        inbox_id=inbox_id,
+        thread_id=thread_id,
+        limit=min(limit, 100),
+        offset=offset,
+    )
 
 
 @mcp.tool()
@@ -155,6 +209,91 @@ async def tool_wait_for_reply(thread_id: str, timeout_seconds: int = 300) -> dic
     return await wait_for_reply(client, thread_id=thread_id, timeout_seconds=timeout_seconds)
 
 
+@mcp.tool()
+async def tool_list_attachments(
+    message_id: str | None = None,
+    thread_id: str | None = None,
+    inbox_id: str | None = None,
+    limit: int = 100,
+) -> dict[str, Any]:
+    """List attachments for a message, thread, or inbox.
+
+    Retrieve metadata for attachments. Exactly one filter must be provided.
+
+    Args:
+        message_id: Filter by message ID
+        thread_id: Filter by thread ID (all messages in thread)
+        inbox_id: Filter by inbox ID (all messages in inbox)
+        limit: Maximum number of results (default: 100)
+
+    Returns:
+        List of attachment metadata with id, message_id, filename, content_type, size.
+    """
+    client = _get_client()
+    return await list_attachments(
+        client,
+        message_id=message_id,
+        thread_id=thread_id,
+        inbox_id=inbox_id,
+        limit=limit,
+    )
+
+
+@mcp.tool()
+async def tool_get_attachment_content(attachment_id: str) -> dict[str, Any]:
+    """Get attachment content as base64.
+
+    Download the binary content of an attachment, returned as base64-encoded data.
+
+    Args:
+        attachment_id: The attachment ID to retrieve
+
+    Returns:
+        Attachment content with base64-encoded data, content_type, and filename.
+    """
+    client = _get_client()
+    return await get_attachment_content(client, attachment_id=attachment_id)
+
+
+@mcp.tool()
+async def tool_send_email_with_attachments(
+    inbox_id: str,
+    recipient: str,
+    subject: str,
+    body: str,
+    attachments: list[dict[str, str]],
+    thread_id: str | None = None,
+) -> dict[str, Any]:
+    """Send an email with attachments.
+
+    Send an email with one or more file attachments.
+
+    Args:
+        inbox_id: The inbox ID to send from
+        recipient: Email address to send to
+        subject: Email subject line
+        body: Email body in Markdown format
+        attachments: List of attachments, each with:
+            - filename: Name of the file (e.g., "report.pdf")
+            - content_type: MIME type (e.g., "application/pdf")
+            - content: Base64-encoded file content
+        thread_id: Optional thread ID if this is a reply
+
+    Returns:
+        Send response with message_id, thread_id, and status.
+    """
+    client = _get_client()
+    return await send_email_with_attachments(
+        client,
+        inbox_id=inbox_id,
+        recipient=recipient,
+        subject=subject,
+        body=body,
+        attachments=attachments,
+        thread_id=thread_id,
+    )
+
+
 # -----------------------------------------------------------------------------
 # Server Entry Points
 # -----------------------------------------------------------------------------

nornweave/models/thread.py

@@ -34,6 +34,7 @@ class ThreadItem(BaseModel):
     recipients: list[str] = Field(default_factory=list, description="Recipients in thread")
     subject: str | None = Field(None, description="Subject of thread")
     preview: str | None = Field(None, description="Text preview of last message in thread")
+    summary: str | None = Field(None, description="LLM-generated thread summary")
     attachments: list[AttachmentMeta] | None = Field(None, description="Attachments in thread")
     last_message_id: str | None = Field(None, description="ID of last message in thread")
     message_count: int = Field(0, description="Number of messages in thread")
@@ -75,6 +76,7 @@ class Thread(BaseModel):
     recipients: list[str] = Field(default_factory=list, description="Recipients in thread")
     subject: str | None = Field(None, description="Subject of thread")
     preview: str | None = Field(None, description="Text preview of last message in thread")
+    summary: str | None = Field(None, description="LLM-generated thread summary")
     attachments: list[AttachmentMeta] | None = Field(None, description="All attachments in thread")
     last_message_id: str | None = Field(None, description="ID of last message in thread")
     message_count: int = Field(0, description="Number of messages in thread")