nornweave 0.1.2__py3-none-any.whl

nornweave/models/thread.py

@@ -0,0 +1,172 @@
+"""Thread models.
+
+Thread models for email conversation grouping.
+"""
+
+from datetime import datetime  # noqa: TC003 - needed at runtime for Pydantic
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from nornweave.models.attachment import AttachmentMeta
+    from nornweave.models.message import Message
+
+
+class ThreadItem(BaseModel):
+    """
+    Thread summary for list views.
+
+    Summary model for thread list views.
+    """
+
+    inbox_id: str = Field(..., description="ID of inbox")
+    thread_id: str = Field(..., alias="id", description="ID of thread")
+    labels: list[str] = Field(default_factory=list, description="Labels of thread")
+    timestamp: datetime | None = Field(
+        None, alias="last_message_at", description="Timestamp of last sent or received message"
+    )
+    received_timestamp: datetime | None = Field(
+        None, description="Timestamp of last received message"
+    )
+    sent_timestamp: datetime | None = Field(None, description="Timestamp of last sent message")
+    senders: list[str] = Field(default_factory=list, description="Senders in thread")
+    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")
+    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")
+    size: int = Field(0, description="Size of thread in bytes")
+    updated_at: datetime | None = Field(None, description="Time at which thread was last updated")
+    created_at: datetime | None = Field(None, description="Time at which thread was created")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def id(self) -> str:
+        """Alias for thread_id for compatibility."""
+        return self.thread_id
+
+    @property
+    def last_message_at(self) -> datetime | None:
+        """Alias for timestamp for backwards compatibility."""
+        return self.timestamp
+
+
+class Thread(BaseModel):
+    """
+    Full thread model with messages.
+
+    Complete thread model with optional message list.
+    """
+
+    inbox_id: str = Field(..., description="ID of inbox")
+    thread_id: str = Field(..., alias="id", description="ID of thread")
+    labels: list[str] = Field(default_factory=list, description="Labels of thread")
+    timestamp: datetime | None = Field(
+        None, alias="last_message_at", description="Timestamp of last sent or received message"
+    )
+    received_timestamp: datetime | None = Field(
+        None, description="Timestamp of last received message"
+    )
+    sent_timestamp: datetime | None = Field(None, description="Timestamp of last sent message")
+    senders: list[str] = Field(default_factory=list, description="Senders in thread")
+    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")
+    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")
+    size: int = Field(0, description="Size of thread in bytes")
+    updated_at: datetime | None = Field(None, description="Time at which thread was last updated")
+    created_at: datetime | None = Field(None, description="Time at which thread was created")
+    # Optional for full thread response - messages ordered by timestamp ascending
+    messages: list[Message] | None = Field(
+        None, description="Messages in thread, ordered by timestamp ascending"
+    )
+    # Internal fields for threading
+    participant_hash: str | None = Field(None, description="Hash of participants for grouping")
+    normalized_subject: str | None = Field(
+        None, description="Normalized subject for subject-based threading"
+    )
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def id(self) -> str:
+        """Alias for thread_id for compatibility."""
+        return self.thread_id
+
+    @property
+    def last_message_at(self) -> datetime | None:
+        """Alias for timestamp for backwards compatibility."""
+        return self.timestamp
+
+    @last_message_at.setter
+    def last_message_at(self, value: datetime | None) -> None:
+        """Setter for last_message_at (maps to timestamp)."""
+        object.__setattr__(self, "timestamp", value)
+
+
+class ListThreadsResponse(BaseModel):
+    """
+    Response for listing threads.
+
+    Paginated response for thread listing.
+    """
+
+    count: int = Field(..., description="Total count of threads")
+    limit: int | None = Field(None, description="Limit applied to results")
+    next_page_token: str | None = Field(None, description="Token for next page")
+    threads: list[ThreadItem] = Field(..., description="Threads ordered by timestamp descending")
+
+    model_config = {"extra": "forbid"}
+
+
+class UpdateThreadRequest(BaseModel):
+    """Request to update thread labels."""
+
+    add_labels: list[str] | None = Field(None, description="Labels to add to thread")
+    remove_labels: list[str] | None = Field(None, description="Labels to remove from thread")
+
+    model_config = {"extra": "forbid"}
+
+
+# Legacy compatibility models
+class ThreadBase(BaseModel):
+    """Shared thread fields (legacy compatibility)."""
+
+    inbox_id: str = Field(..., description="Owning inbox id")
+    subject: str = Field(..., description="Thread subject")
+    last_message_at: datetime | None = Field(None, description="Last message timestamp")
+    participant_hash: str | None = Field(None, description="Hash of participants for grouping")
+
+
+class ThreadCreate(BaseModel):
+    """Payload to create a thread (used on ingestion)."""
+
+    inbox_id: str = Field(..., description="Owning inbox id")
+    subject: str = Field(..., description="Thread subject")
+    last_message_at: datetime | None = Field(None, description="Last message timestamp")
+    participant_hash: str | None = Field(None, description="Hash of participants for grouping")
+    senders: list[str] = Field(default_factory=list, description="Senders in thread")
+    recipients: list[str] = Field(default_factory=list, description="Recipients in thread")
+    normalized_subject: str | None = Field(None, description="Normalized subject for threading")
+
+    model_config = {"extra": "forbid"}
+
+
+class ThreadSummary(BaseModel):
+    """Summary for list views (e.g. recent threads). Legacy compatibility."""
+
+    id: str
+    subject: str
+    last_message_at: datetime | None
+    message_count: int = 0
+
+    model_config = {"extra": "forbid"}
+
+
+# Note: Forward reference resolution (model_rebuild) is done in __init__.py
+# after all models are imported to avoid circular import issues.

nornweave/muninn/__init__.py

@@ -0,0 +1,14 @@
+"""Muninn: MCP write tools (Memory).
+
+This module provides MCP tools (actions) for AI agents.
+Named after Odin's raven of memory.
+"""
+
+from nornweave.muninn.tools import (
+    create_inbox,
+    search_email,
+    send_email,
+    wait_for_reply,
+)
+
+__all__ = ["create_inbox", "search_email", "send_email", "wait_for_reply"]

nornweave/muninn/tools.py

@@ -0,0 +1,207 @@
+"""MCP tools: create_inbox, send_email, search_email, wait_for_reply.
+
+Tools provide actions that AI agents can perform.
+"""
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from nornweave.huginn.client import NornWeaveClient
+
+
+async def create_inbox(
+    client: NornWeaveClient,
+    name: str,
+    username: str,
+) -> dict[str, Any]:
+    """Create a new inbox.
+
+    Provision a new email address for the agent.
+
+    Args:
+        client: NornWeave API client.
+        name: Display name for the inbox.
+        username: Local part of email address (before @).
+
+    Returns:
+        Created inbox with id, email_address, name.
+
+    Raises:
+        Exception: If inbox creation fails.
+    """
+    try:
+        result = await client.create_inbox(name=name, email_username=username)
+        return {
+            "id": result["id"],
+            "email_address": result["email_address"],
+            "name": result.get("name"),
+        }
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 409:
+            raise Exception(f"Email address with username '{username}' already exists") from e
+        if e.response.status_code == 422:
+            raise Exception(f"Invalid username: {username}") from e
+        raise Exception(f"Failed to create inbox: {e.response.status_code}") from e
+
+
+async def send_email(
+    client: NornWeaveClient,
+    inbox_id: str,
+    recipient: str,
+    subject: str,
+    body: str,
+    thread_id: str | None = None,
+) -> dict[str, Any]:
+    """Send an email.
+
+    Send an email from an inbox, automatically converting Markdown to HTML.
+
+    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.
+        thread_id: Optional thread ID for replies.
+
+    Returns:
+        Send response with message_id, thread_id, status.
+
+    Raises:
+        Exception: If sending fails.
+    """
+    try:
+        result = await client.send_message(
+            inbox_id=inbox_id,
+            to=[recipient],
+            subject=subject,
+            body=body,
+            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
+        raise Exception(f"Failed to send email: {e.response.status_code}") from e
+
+
+async def search_email(
+    client: NornWeaveClient,
+    query: str,
+    inbox_id: str,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Search for emails.
+
+    Find relevant messages in an inbox by query text.
+
+    Args:
+        client: NornWeave API client.
+        query: Search query.
+        inbox_id: Inbox to search in.
+        limit: Maximum number of results (default: 10).
+
+    Returns:
+        Search results with matching messages.
+
+    Raises:
+        Exception: If search fails.
+    """
+    try:
+        result = await client.search_messages(
+            query=query,
+            inbox_id=inbox_id,
+            limit=limit,
+        )
+
+        # Format results for MCP
+        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"),
+                }
+            )
+
+        return {
+            "query": query,
+            "count": 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(f"Search failed: {e.response.status_code}") from e
+
+
+async def wait_for_reply(
+    client: NornWeaveClient,
+    thread_id: str,
+    timeout_seconds: int = 300,
+    poll_interval: int = 5,
+) -> dict[str, Any]:
+    """Wait for a reply in a thread (experimental).
+
+    Block execution until a new email arrives in a thread.
+    Uses polling to check for new messages.
+
+    Args:
+        client: NornWeave API client.
+        thread_id: Thread to wait on.
+        timeout_seconds: Maximum wait time (default: 300 seconds / 5 minutes).
+        poll_interval: Seconds between polls (default: 5).
+
+    Returns:
+        The new message content if received, or timeout indicator.
+
+    Raises:
+        Exception: If thread not found.
+    """
+    try:
+        # Get initial message count
+        initial_count = await client.get_thread_message_count(thread_id)
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            raise Exception(f"Thread '{thread_id}' not found") from e
+        raise Exception(f"Failed to access thread: {e.response.status_code}") from e
+
+    elapsed = 0
+    while elapsed < timeout_seconds:
+        await asyncio.sleep(poll_interval)
+        elapsed += poll_interval
+
+        try:
+            current_count = await client.get_thread_message_count(thread_id)
+
+            if current_count > initial_count:
+                # New message arrived
+                latest = await client.get_latest_message(thread_id)
+                if latest:
+                    return {
+                        "received": True,
+                        "message": {
+                            "author": latest.get("author"),
+                            "content": latest.get("content", ""),
+                            "timestamp": latest.get("timestamp"),
+                        },
+                    }
+        except httpx.HTTPStatusError:
+            # Ignore transient errors during polling
+            pass
+
+    # Timeout reached
+    return {
+        "received": False,
+        "timeout": True,
+        "waited_seconds": timeout_seconds,
+    }

nornweave/search/__init__.py

@@ -0,0 +1 @@
+"""Semantic search (Phase 3)."""

nornweave/search/embeddings.py

@@ -0,0 +1 @@
+"""Vector embedding generation. Phase 3. Placeholder."""

nornweave/search/vector_store.py

@@ -0,0 +1 @@
+"""pgvector integration. Phase 3. Placeholder."""

nornweave/skuld/__init__.py

@@ -0,0 +1 @@
+"""Skuld (The Prophecy): API and outbound sending."""

nornweave/skuld/rate_limiter.py

@@ -0,0 +1 @@
+"""Rate limiting (token bucket). Phase 3. Placeholder."""

nornweave/skuld/scheduler.py

@@ -0,0 +1 @@
+"""Scheduled replies. Phase 3. Placeholder."""

nornweave/skuld/sender.py

@@ -0,0 +1,25 @@
+"""Email sending via configured provider. Placeholder."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nornweave.core.interfaces import EmailProvider
+
+
+async def send_via_provider(
+    provider: EmailProvider,
+    to: list[str],
+    subject: str,
+    body: str,
+    *,
+    from_address: str,
+    reply_to: str | None = None,
+) -> str:
+    """Send email through provider. Returns provider message id."""
+    return await provider.send_email(
+        to=to,
+        subject=subject,
+        body=body,
+        from_address=from_address,
+        reply_to=reply_to,
+    )

nornweave/skuld/webhooks.py

@@ -0,0 +1 @@
+"""Outbound webhook delivery. Phase 3. Placeholder."""

nornweave/storage/__init__.py

@@ -0,0 +1,20 @@
+"""Attachment storage backends.
+
+NornWeave supports multiple storage backends:
+- LocalFilesystemStorage: Store on local disk (development)
+- S3Storage: Store in AWS S3 (production)
+- GCSStorage: Store in Google Cloud Storage (production)
+- DatabaseBlobStorage: Store as database BLOBs (simple deployment)
+"""
+
+from nornweave.storage.database import DatabaseBlobStorage
+from nornweave.storage.gcs import GCSStorage
+from nornweave.storage.local import LocalFilesystemStorage
+from nornweave.storage.s3 import S3Storage
+
+__all__ = [
+    "DatabaseBlobStorage",
+    "GCSStorage",
+    "LocalFilesystemStorage",
+    "S3Storage",
+]

nornweave/storage/database.py

@@ -0,0 +1,165 @@
+"""Database blob storage backend for attachments.
+
+Stores attachment content directly in the database as BLOBs.
+Suitable for simple deployments with small attachments.
+Not recommended for large files or high-volume scenarios.
+"""
+
+import hashlib
+import hmac
+import time
+from datetime import timedelta
+from urllib.parse import urlencode
+
+from nornweave.core.storage import AttachmentMetadata, AttachmentStorageBackend, StorageResult
+
+
+class DatabaseBlobStorage(AttachmentStorageBackend):
+    """Store attachments as BLOBs in database.
+
+    This backend stores attachment content directly in the attachments
+    table's 'content' column. Download URLs point to an API endpoint
+    that retrieves content from the database.
+
+    Good for:
+    - Simple deployments without external storage
+    - Small attachments
+    - Development/testing
+
+    Not recommended for:
+    - Large files (>1MB)
+    - High-volume production systems
+    """
+
+    def __init__(
+        self,
+        serve_url_prefix: str = "/v1/attachments",
+        signing_secret: str | None = None,
+    ) -> None:
+        """
+        Initialize database storage.
+
+        Args:
+            serve_url_prefix: URL prefix for download URLs
+            signing_secret: Secret for signing download URLs
+        """
+        self.serve_url_prefix = serve_url_prefix.rstrip("/")
+        self._signing_secret = signing_secret or "default-signing-secret"
+
+    @property
+    def backend_name(self) -> str:
+        return "database"
+
+    async def store(
+        self,
+        attachment_id: str,
+        content: bytes,
+        _metadata: AttachmentMetadata,
+    ) -> StorageResult:
+        """
+        Store attachment in database.
+
+        Note: The actual database write is handled by the storage layer
+        that creates the AttachmentORM record. This method just returns
+        the storage result with the attachment_id as the key.
+
+        The caller is responsible for setting the 'content' column
+        on the AttachmentORM model before committing.
+        """
+        return StorageResult(
+            storage_key=attachment_id,  # Use attachment_id as the key
+            size_bytes=len(content),
+            content_hash=self.compute_hash(content),
+            backend=self.backend_name,
+        )
+
+    async def retrieve(self, storage_key: str) -> bytes:
+        """
+        Retrieve attachment from database.
+
+        Note: This method would normally query the database, but since
+        we want to avoid direct database access in the storage backend,
+        the actual retrieval should be done through the storage layer.
+
+        This implementation is a placeholder that should be overridden
+        by the application code that has access to the database session.
+        """
+        raise NotImplementedError(
+            "Database storage retrieval should be done through the storage layer"
+        )
+
+    async def delete(self, storage_key: str) -> bool:
+        """
+        Delete attachment from database.
+
+        Note: The actual database delete is handled by cascade when
+        the message is deleted, or explicitly through the storage layer.
+        """
+        raise NotImplementedError(
+            "Database storage deletion should be done through the storage layer"
+        )
+
+    async def get_download_url(
+        self,
+        storage_key: str,
+        expires_in: timedelta = timedelta(hours=1),
+        filename: str | None = None,
+    ) -> str:
+        """Generate a signed download URL for API-based retrieval."""
+        attachment_id = storage_key
+
+        # Create signed token
+        expiry = int(time.time() + expires_in.total_seconds())
+        signature = self._sign_url(attachment_id, expiry)
+
+        # Build URL with query params
+        params = {"token": signature, "expires": str(expiry)}
+        if filename:
+            params["filename"] = filename
+
+        return f"{self.serve_url_prefix}/{attachment_id}/download?{urlencode(params)}"
+
+    async def exists(self, storage_key: str) -> bool:
+        """
+        Check if attachment exists in database.
+
+        Note: Should be done through the storage layer with database access.
+        """
+        raise NotImplementedError(
+            "Database storage existence check should be done through the storage layer"
+        )
+
+    def _sign_url(self, attachment_id: str, expiry: int) -> str:
+        """Create HMAC signature for URL."""
+        message = f"{attachment_id}:{expiry}"
+        signature = hmac.new(
+            self._signing_secret.encode(),
+            message.encode(),
+            hashlib.sha256,
+        ).hexdigest()[:32]
+        return signature
+
+    def verify_signed_url(
+        self,
+        attachment_id: str,
+        token: str,
+        expires: int,
+    ) -> bool:
+        """
+        Verify a signed download URL.
+
+        Args:
+            attachment_id: The attachment ID from the URL
+            token: The signature token from the URL
+            expires: The expiry timestamp from the URL
+
+        Returns:
+            True if signature is valid and not expired
+        """
+        # Check expiry
+        if expires < time.time():
+            return False
+
+        # Verify signature
+        expected = self._sign_url(attachment_id, expires)
+        return hmac.compare_digest(token, expected)