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

nornweave/muninn/tools.py

@@ -95,55 +95,133 @@ async def send_email(
 async def search_email(
     client: NornWeaveClient,
     query: str,
-    inbox_id: str,
+    inbox_id: str | None = None,
+    thread_id: str | None = None,
     limit: int = 10,
+    offset: int = 0,
 ) -> dict[str, Any]:
-    """Search for emails.
+    """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:
         client: NornWeave API client.
-        query: Search query.
-        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).
+        offset: Pagination offset (default: 0).
 
     Returns:
-        Search results with matching messages.
+        Search results with matching messages including expanded fields.
 
     Raises:
-        Exception: If search fails.
+        Exception: If search fails or no filter provided.
     """
+    if inbox_id is None and thread_id is None:
+        raise Exception("At least one filter (inbox_id or thread_id) is required")
+
     try:
-        result = await client.search_messages(
-            query=query,
+        result = await client.list_messages(
             inbox_id=inbox_id,
+            thread_id=thread_id,
+            q=query,
             limit=limit,
+            offset=offset,
         )
 
-        # Format results for MCP
+        # Format results for MCP with expanded fields
         messages = []
         for item in result.get("items", []):
-            messages.append(
-                {
-                    "id": item["id"],
-                    "thread_id": item["thread_id"],
-                    "content": item.get("content_clean", ""),
-                    "created_at": item.get("created_at"),
-                }
-            )
+            messages.append(_format_message_for_mcp(item))
 
         return {
             "query": query,
             "count": len(messages),
+            "total": result.get("total", len(messages)),
             "messages": messages,
         }
     except httpx.HTTPStatusError as e:
         if e.response.status_code == 404:
-            raise Exception(f"Inbox '{inbox_id}' not found") from e
+            raise Exception("Inbox or thread not found") from e
+        if e.response.status_code == 422:
+            raise Exception("At least one filter (inbox_id or thread_id) is required") from e
         raise Exception(f"Search failed: {e.response.status_code}") from e
 
 
+async def list_messages(
+    client: NornWeaveClient,
+    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:
+        client: NornWeave API client.
+        inbox_id: Filter by inbox ID (optional).
+        thread_id: Filter by thread ID (optional).
+        limit: Maximum number of results (default: 50).
+        offset: Pagination offset (default: 0).
+
+    Returns:
+        List of messages with expanded fields.
+
+    Raises:
+        Exception: If listing fails or no filter provided.
+    """
+    if inbox_id is None and thread_id is None:
+        raise Exception("At least one filter (inbox_id or thread_id) is required")
+
+    try:
+        result = await client.list_messages(
+            inbox_id=inbox_id,
+            thread_id=thread_id,
+            limit=limit,
+            offset=offset,
+        )
+
+        # Format results for MCP with expanded fields
+        messages = []
+        for item in result.get("items", []):
+            messages.append(_format_message_for_mcp(item))
+
+        return {
+            "count": len(messages),
+            "total": result.get("total", len(messages)),
+            "messages": messages,
+        }
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception("Inbox or thread not found") from e
+        if e.response.status_code == 422:
+            raise Exception("At least one filter (inbox_id or thread_id) is required") from e
+        raise Exception(f"List messages failed: {e.response.status_code}") from e
+
+
+def _format_message_for_mcp(item: dict[str, Any]) -> dict[str, Any]:
+    """Format a message response for MCP tools with all expanded fields."""
+    return {
+        "id": item["id"],
+        "thread_id": item["thread_id"],
+        "inbox_id": item["inbox_id"],
+        "direction": item.get("direction"),
+        "subject": item.get("subject"),
+        "from_address": item.get("from_address"),
+        "to_addresses": item.get("to_addresses", []),
+        "cc_addresses": item.get("cc_addresses"),
+        "text": item.get("text"),
+        "content_clean": item.get("content_clean", ""),
+        "timestamp": item.get("timestamp"),
+        "preview": item.get("preview"),
+        "labels": item.get("labels", []),
+        "created_at": item.get("created_at"),
+    }
+
+
 async def wait_for_reply(
     client: NornWeaveClient,
     thread_id: str,
@@ -205,3 +283,173 @@ async def wait_for_reply(
         "timeout": True,
         "waited_seconds": timeout_seconds,
     }
+
+
+async def list_attachments(
+    client: NornWeaveClient,
+    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:
+        client: NornWeave API client.
+        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 objects.
+
+    Raises:
+        Exception: If filter is missing or invalid.
+    """
+    # Validate exactly one filter
+    filters = [f for f in [message_id, thread_id, inbox_id] if f is not None]
+    if len(filters) == 0:
+        raise Exception("Exactly one filter required: message_id, thread_id, or inbox_id")
+    if len(filters) > 1:
+        raise Exception("Only one filter allowed: message_id, thread_id, or inbox_id")
+
+    try:
+        result = await client.list_attachments(
+            message_id=message_id,
+            thread_id=thread_id,
+            inbox_id=inbox_id,
+            limit=limit,
+        )
+
+        # Format results for MCP
+        attachments = []
+        for item in result.get("items", []):
+            attachments.append(
+                {
+                    "id": item["id"],
+                    "message_id": item["message_id"],
+                    "filename": item["filename"],
+                    "content_type": item["content_type"],
+                    "size": item["size"],
+                }
+            )
+
+        return {
+            "count": len(attachments),
+            "attachments": attachments,
+        }
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 400:
+            raise Exception(
+                "Invalid filter: exactly one of message_id, thread_id, or inbox_id required"
+            ) from e
+        if e.response.status_code == 404:
+            raise Exception("Resource not found") from e
+        raise Exception(f"Failed to list attachments: {e.response.status_code}") from e
+
+
+async def get_attachment_content(
+    client: NornWeaveClient,
+    attachment_id: str,
+) -> dict[str, Any]:
+    """Retrieve attachment content as base64.
+
+    Download the binary content of an attachment, encoded as base64.
+
+    Args:
+        client: NornWeave API client.
+        attachment_id: The attachment ID to retrieve.
+
+    Returns:
+        Attachment content with base64-encoded data, content_type, and filename.
+
+    Raises:
+        Exception: If attachment not found.
+    """
+    try:
+        result = await client.get_attachment_content(
+            attachment_id=attachment_id,
+            response_format="base64",
+        )
+        return {
+            "content": result["content"],
+            "content_type": result["content_type"],
+            "filename": result["filename"],
+        }
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception(f"Attachment '{attachment_id}' not found") from e
+        if e.response.status_code == 401:
+            raise Exception("Attachment download URL expired or invalid") from e
+        raise Exception(f"Failed to get attachment content: {e.response.status_code}") from e
+
+
+async def send_email_with_attachments(
+    client: NornWeaveClient,
+    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 attachments. Each attachment should include
+    filename, content_type, and base64-encoded content.
+
+    Args:
+        client: NornWeave API client.
+        inbox_id: The inbox to send from.
+        recipient: Email address to send to.
+        subject: Email subject.
+        body: Markdown content for the email body.
+        attachments: List of attachment dicts with keys:
+            - filename: Name of the file
+            - content_type: MIME type (e.g., "application/pdf")
+            - content: Base64-encoded file content
+        thread_id: Optional thread ID for replies.
+
+    Returns:
+        Send response with message_id, thread_id, status.
+
+    Raises:
+        Exception: If sending fails or attachments are invalid.
+    """
+    # Validate attachments
+    if not attachments:
+        raise Exception(
+            "At least one attachment is required. Use send_email for messages without attachments."
+        )
+
+    for i, att in enumerate(attachments):
+        if not att.get("filename"):
+            raise Exception(f"Attachment {i} missing filename")
+        if not att.get("content_type"):
+            raise Exception(f"Attachment {i} missing content_type")
+        if not att.get("content"):
+            raise Exception(f"Attachment {i} missing content (base64)")
+
+    try:
+        result = await client.send_message_with_attachments(
+            inbox_id=inbox_id,
+            to=[recipient],
+            subject=subject,
+            body=body,
+            attachments=attachments,
+            reply_to_thread_id=thread_id,
+        )
+        return {
+            "message_id": result["id"],
+            "thread_id": result["thread_id"],
+            "status": result.get("status", "sent"),
+        }
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception(f"Inbox '{inbox_id}' not found") from e
+        if e.response.status_code == 400:
+            raise Exception("Invalid attachment data (check base64 encoding)") from e
+        raise Exception(f"Failed to send email: {e.response.status_code}") from e

nornweave/storage/database.py

@@ -54,7 +54,7 @@ class DatabaseBlobStorage(AttachmentStorageBackend):
         self,
         attachment_id: str,
         content: bytes,
-        _metadata: AttachmentMetadata,
+        metadata: AttachmentMetadata,  # noqa: ARG002 - required by interface
     ) -> StorageResult:
         """
         Store attachment in database.

nornweave/urdr/adapters/base.py

@@ -1,13 +1,20 @@
 """Base storage adapter with shared SQLAlchemy functionality."""
 
 import uuid
-from datetime import UTC, datetime, timedelta
+from datetime import UTC, date, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
-from sqlalchemy import or_, select
+from sqlalchemy import func, or_, select
 
 from nornweave.core.interfaces import StorageInterface
-from nornweave.urdr.orm import AttachmentORM, EventORM, InboxORM, MessageORM, ThreadORM
+from nornweave.urdr.orm import (
+    AttachmentORM,
+    EventORM,
+    InboxORM,
+    LlmTokenUsageORM,
+    MessageORM,
+    ThreadORM,
+)
 
 if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncSession
@@ -115,6 +122,13 @@ class BaseSQLAlchemyAdapter(StorageInterface):
         orm_thread.subject = thread.subject
         orm_thread.last_message_at = thread.last_message_at
         orm_thread.participant_hash = thread.participant_hash
+        if thread.timestamp is not None:
+            orm_thread.timestamp = thread.timestamp
+        orm_thread.message_count = thread.message_count
+        orm_thread.preview = thread.preview
+        orm_thread.senders = thread.senders
+        orm_thread.recipients = thread.recipients
+        orm_thread.summary = thread.summary
         await self._session.flush()
         await self._session.refresh(orm_thread)
         return orm_thread.to_pydantic()
@@ -221,6 +235,63 @@ class BaseSQLAlchemyAdapter(StorageInterface):
         result = await self._session.execute(stmt)
         return [row.to_pydantic() for row in result.scalars().all()]
 
+    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.
+
+        Returns tuple of (messages, total_count).
+        Override in subclass for dialect-specific search (ILIKE for Postgres).
+        """
+        # Build base query with filters
+        base_conditions = []
+        if inbox_id:
+            base_conditions.append(MessageORM.inbox_id == inbox_id)
+        if thread_id:
+            base_conditions.append(MessageORM.thread_id == thread_id)
+
+        # Text search condition
+        if query:
+            pattern = f"%{query}%"
+            # Subquery for attachment filename search
+            attachment_subquery = (
+                select(AttachmentORM.message_id)
+                .where(AttachmentORM.filename.like(pattern))
+                .distinct()
+                .scalar_subquery()
+            )
+            text_condition = or_(
+                MessageORM.subject.like(pattern),
+                MessageORM.content_raw.like(pattern),
+                MessageORM.from_address.like(pattern),
+                MessageORM.id.in_(attachment_subquery),
+            )
+            base_conditions.append(text_condition)
+
+        # Count query
+        count_stmt = select(func.count(MessageORM.id))
+        if base_conditions:
+            count_stmt = count_stmt.where(*base_conditions)
+        count_result = await self._session.execute(count_stmt)
+        total = count_result.scalar() or 0
+
+        # Data query with pagination
+        data_stmt = select(MessageORM)
+        if base_conditions:
+            data_stmt = data_stmt.where(*base_conditions)
+        data_stmt = data_stmt.order_by(MessageORM.created_at.desc()).limit(limit).offset(offset)
+        data_result = await self._session.execute(data_stmt)
+        messages = [row.to_pydantic() for row in data_result.scalars().all()]
+
+        return messages, total
+
     # -------------------------------------------------------------------------
     # Event methods
     # -------------------------------------------------------------------------
@@ -334,6 +405,76 @@ class BaseSQLAlchemyAdapter(StorageInterface):
             for row in result.scalars().all()
         ]
 
+    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."""
+        # Join attachments with messages to filter by thread_id
+        stmt = (
+            select(AttachmentORM)
+            .join(MessageORM, AttachmentORM.message_id == MessageORM.id)
+            .where(MessageORM.thread_id == thread_id)
+            .order_by(AttachmentORM.created_at)
+            .limit(limit)
+            .offset(offset)
+        )
+        result = await self._session.execute(stmt)
+        return [
+            {
+                "id": row.id,
+                "message_id": row.message_id,
+                "filename": row.filename,
+                "content_type": row.content_type,
+                "size_bytes": row.size_bytes,
+                "disposition": row.disposition,
+                "content_id": row.content_id,
+                "storage_path": row.storage_path,
+                "storage_backend": row.storage_backend,
+                "content_hash": row.content_hash,
+                "created_at": row.created_at,
+            }
+            for row in result.scalars().all()
+        ]
+
+    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."""
+        # Join attachments with messages to filter by inbox_id
+        stmt = (
+            select(AttachmentORM)
+            .join(MessageORM, AttachmentORM.message_id == MessageORM.id)
+            .where(MessageORM.inbox_id == inbox_id)
+            .order_by(AttachmentORM.created_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+        result = await self._session.execute(stmt)
+        return [
+            {
+                "id": row.id,
+                "message_id": row.message_id,
+                "filename": row.filename,
+                "content_type": row.content_type,
+                "size_bytes": row.size_bytes,
+                "disposition": row.disposition,
+                "content_id": row.content_id,
+                "storage_path": row.storage_path,
+                "storage_backend": row.storage_backend,
+                "content_hash": row.content_hash,
+                "created_at": row.created_at,
+            }
+            for row in result.scalars().all()
+        ]
+
     async def delete_attachment(self, attachment_id: str) -> bool:
         """Delete an attachment."""
         orm_attachment = await self._session.get(AttachmentORM, attachment_id)
@@ -383,3 +524,32 @@ class BaseSQLAlchemyAdapter(StorageInterface):
         result = await self._session.execute(stmt)
         orm_thread = result.scalar_one_or_none()
         return orm_thread.to_pydantic() if orm_thread else None
+
+    # -------------------------------------------------------------------------
+    # LLM Token Usage methods
+    # -------------------------------------------------------------------------
+    async def get_token_usage(self, usage_date: date) -> int:
+        """Get total tokens used for a given date."""
+        stmt = select(LlmTokenUsageORM.tokens_used).where(
+            LlmTokenUsageORM.date == usage_date,
+        )
+        result = await self._session.execute(stmt)
+        row = result.scalar_one_or_none()
+        return row if row is not None else 0
+
+    async def record_token_usage(self, usage_date: date, tokens: int) -> None:
+        """Record token usage for a given date (upsert: create or increment)."""
+        stmt = select(LlmTokenUsageORM).where(LlmTokenUsageORM.date == usage_date)
+        result = await self._session.execute(stmt)
+        usage_row = result.scalar_one_or_none()
+
+        if usage_row is None:
+            usage_row = LlmTokenUsageORM(
+                date=usage_date,
+                tokens_used=tokens,
+            )
+            self._session.add(usage_row)
+        else:
+            usage_row.tokens_used = usage_row.tokens_used + tokens
+
+        await self._session.flush()

nornweave/urdr/migrations/versions/20260205_0003_llm_thread_summary.py

@@ -0,0 +1,54 @@
+"""Add LLM thread summary: summary column on threads, llm_token_usage table.
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-02-05
+
+"""
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "0003"
+down_revision: str | None = "0002"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Add summary column to threads and create llm_token_usage table."""
+    # ==========================================================================
+    # Add summary column to threads table
+    # ==========================================================================
+    op.add_column(
+        "threads",
+        sa.Column("summary", sa.Text(), nullable=True),
+    )
+
+    # ==========================================================================
+    # Create llm_token_usage table
+    # ==========================================================================
+    op.create_table(
+        "llm_token_usage",
+        sa.Column("date", sa.Date(), nullable=False),
+        sa.Column("tokens_used", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.PrimaryKeyConstraint("date"),
+    )
+
+
+def downgrade() -> None:
+    """Remove summary column from threads and drop llm_token_usage table."""
+    op.drop_table("llm_token_usage")
+    op.drop_column("threads", "summary")

nornweave/urdr/orm.py

@@ -1,11 +1,12 @@
 """SQLAlchemy ORM models for Urðr storage layer."""
 
 import uuid
-from datetime import datetime
+from datetime import date, datetime
 from typing import Any
 
 from sqlalchemy import (
     JSON,
+    Date,
     DateTime,
     ForeignKey,
     Index,
@@ -171,6 +172,7 @@ class ThreadORM(Base):
         index=True,
     )
     preview: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    summary: Mapped[str | None] = mapped_column(Text, nullable=True)
 
     # Stats
     last_message_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
@@ -211,6 +213,7 @@ class ThreadORM(Base):
             recipients=self.recipients or [],
             subject=self.subject,
             preview=self.preview,
+            summary=self.summary,
             attachments=None,  # Load separately if needed
             last_message_id=self.last_message_id,
             message_count=self.message_count,
@@ -236,6 +239,7 @@ class ThreadORM(Base):
             subject=thread.subject,
             normalized_subject=thread.normalized_subject,
             preview=thread.preview,
+            summary=thread.summary,
             last_message_id=thread.last_message_id,
             message_count=thread.message_count,
             size=thread.size,
@@ -639,3 +643,25 @@ class EventORM(Base):
             thread_id=event.thread_id,
             message_id=event.message_id,
         )
+
+
+class LlmTokenUsageORM(Base):
+    """Daily LLM token usage tracking."""
+
+    __tablename__ = "llm_token_usage"
+
+    date: Mapped[date] = mapped_column(
+        Date,
+        primary_key=True,
+    )
+    tokens_used: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )