nornweave 0.1.2__py3-none-any.whl

nornweave/yggdrasil/routes/v1/inboxes.py

@@ -0,0 +1,124 @@
+"""Inbox endpoints."""
+
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+
+from nornweave.core.config import Settings, get_settings
+from nornweave.core.interfaces import StorageInterface  # noqa: TC001 - needed at runtime
+from nornweave.models.inbox import Inbox, InboxCreate
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+
+
+class InboxResponse(BaseModel):
+    """Response model for inbox."""
+
+    id: str
+    email_address: str
+    name: str | None
+    provider_config: dict[str, Any]
+
+
+class InboxListResponse(BaseModel):
+    """Response model for inbox list."""
+
+    items: list[InboxResponse]
+    count: int
+
+
+@router.post("/inboxes", response_model=InboxResponse, status_code=status.HTTP_201_CREATED)
+async def create_inbox(
+    payload: InboxCreate,
+    storage: StorageInterface = Depends(get_storage),
+    settings: Settings = Depends(get_settings),
+) -> InboxResponse:
+    """Create a new inbox.
+
+    The email address is constructed from the username and configured domain.
+    """
+    # Construct full email address
+    email_address = f"{payload.email_username}@{settings.email_domain}"
+
+    # Check if email already exists
+    existing = await storage.get_inbox_by_email(email_address)
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Inbox with email {email_address} already exists",
+        )
+
+    # Create inbox
+    inbox = Inbox(
+        id=str(uuid.uuid4()),
+        email_address=email_address,
+        name=payload.name,
+        provider_config={},
+    )
+
+    created = await storage.create_inbox(inbox)
+    return InboxResponse(
+        id=created.id,
+        email_address=created.email_address,
+        name=created.name,
+        provider_config=created.provider_config,
+    )
+
+
+@router.get("/inboxes", response_model=InboxListResponse)
+async def list_inboxes(
+    limit: int = 50,
+    offset: int = 0,
+    storage: StorageInterface = Depends(get_storage),
+) -> InboxListResponse:
+    """List all inboxes."""
+    inboxes = await storage.list_inboxes(limit=limit, offset=offset)
+    return InboxListResponse(
+        items=[
+            InboxResponse(
+                id=i.id,
+                email_address=i.email_address,
+                name=i.name,
+                provider_config=i.provider_config,
+            )
+            for i in inboxes
+        ],
+        count=len(inboxes),
+    )
+
+
+@router.get("/inboxes/{inbox_id}", response_model=InboxResponse)
+async def get_inbox(
+    inbox_id: str,
+    storage: StorageInterface = Depends(get_storage),
+) -> InboxResponse:
+    """Get an inbox by ID."""
+    inbox = await storage.get_inbox(inbox_id)
+    if inbox is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {inbox_id} not found",
+        )
+    return InboxResponse(
+        id=inbox.id,
+        email_address=inbox.email_address,
+        name=inbox.name,
+        provider_config=inbox.provider_config,
+    )
+
+
+@router.delete("/inboxes/{inbox_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_inbox(
+    inbox_id: str,
+    storage: StorageInterface = Depends(get_storage),
+) -> None:
+    """Delete an inbox."""
+    deleted = await storage.delete_inbox(inbox_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {inbox_id} not found",
+        )

nornweave/yggdrasil/routes/v1/messages.py

@@ -0,0 +1,200 @@
+"""Message endpoints."""
+
+import contextlib
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from nornweave.core.interfaces import (  # noqa: TC001 - needed at runtime for FastAPI
+    EmailProvider,
+    StorageInterface,
+)
+from nornweave.models.message import Message, MessageDirection
+from nornweave.models.thread import Thread
+from nornweave.yggdrasil.dependencies import get_email_provider, get_storage
+
+router = APIRouter()
+
+
+class MessageResponse(BaseModel):
+    """Response model for a message."""
+
+    id: str
+    thread_id: str
+    inbox_id: str
+    direction: str
+    provider_message_id: str | None
+    content_raw: str
+    content_clean: str
+    metadata: dict[str, Any]
+    created_at: datetime | None
+
+
+class MessageListResponse(BaseModel):
+    """Response model for message list."""
+
+    items: list[MessageResponse]
+    count: int
+
+
+class SendMessageRequest(BaseModel):
+    """Request to send an outbound message."""
+
+    inbox_id: str
+    to: list[str] = Field(..., min_length=1)
+    subject: str = Field(..., min_length=1)
+    body: str = Field(..., description="Markdown body content")
+    reply_to_thread_id: str | None = None
+
+
+class SendMessageResponse(BaseModel):
+    """Response after sending a message."""
+
+    id: str
+    thread_id: str
+    provider_message_id: str | None
+    status: str
+
+
+def _message_to_response(msg: Message) -> MessageResponse:
+    """Convert Message model to response."""
+    return MessageResponse(
+        id=msg.id,
+        thread_id=msg.thread_id,
+        inbox_id=msg.inbox_id,
+        direction=msg.direction.value,
+        provider_message_id=msg.provider_message_id,
+        content_raw=msg.content_raw,
+        content_clean=msg.content_clean,
+        metadata=msg.metadata,
+        created_at=msg.created_at,
+    )
+
+
+@router.get("/messages", response_model=MessageListResponse)
+async def list_messages(
+    inbox_id: str,
+    limit: int = 50,
+    offset: int = 0,
+    storage: StorageInterface = Depends(get_storage),
+) -> MessageListResponse:
+    """List messages for an inbox."""
+    # Verify inbox exists
+    inbox = await storage.get_inbox(inbox_id)
+    if inbox is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {inbox_id} not found",
+        )
+
+    messages = await storage.list_messages_for_inbox(
+        inbox_id,
+        limit=limit,
+        offset=offset,
+    )
+
+    return MessageListResponse(
+        items=[_message_to_response(m) for m in messages],
+        count=len(messages),
+    )
+
+
+@router.get("/messages/{message_id}", response_model=MessageResponse)
+async def get_message(
+    message_id: str,
+    storage: StorageInterface = Depends(get_storage),
+) -> MessageResponse:
+    """Get a message by ID."""
+    message = await storage.get_message(message_id)
+    if message is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Message {message_id} not found",
+        )
+    return _message_to_response(message)
+
+
+@router.post("/messages", response_model=SendMessageResponse, status_code=status.HTTP_201_CREATED)
+async def send_message(
+    payload: SendMessageRequest,
+    storage: StorageInterface = Depends(get_storage),
+    email_provider: EmailProvider = Depends(get_email_provider),
+) -> SendMessageResponse:
+    """Send an outbound message.
+
+    If reply_to_thread_id is provided, the message is added to that thread.
+    Otherwise, a new thread is created.
+    """
+    # Get inbox
+    inbox = await storage.get_inbox(payload.inbox_id)
+    if inbox is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {payload.inbox_id} not found",
+        )
+
+    # Get or create thread
+    thread_id: str
+    if payload.reply_to_thread_id:
+        thread = await storage.get_thread(payload.reply_to_thread_id)
+        if thread is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Thread {payload.reply_to_thread_id} not found",
+            )
+        thread_id = thread.id
+    else:
+        # Create a new thread
+        new_thread = Thread(
+            thread_id=str(uuid.uuid4()),
+            inbox_id=payload.inbox_id,
+            subject=payload.subject,
+            timestamp=datetime.now(UTC),
+            participant_hash=None,  # Will be set when we have participants
+        )
+        created_thread = await storage.create_thread(new_thread)
+        thread_id = created_thread.id
+
+    # Send email via provider
+    # Log error but continue to store the message attempt
+    provider_message_id: str | None = None
+    with contextlib.suppress(Exception):
+        provider_message_id = await email_provider.send_email(
+            to=payload.to,
+            subject=payload.subject,
+            body=payload.body,
+            from_address=inbox.email_address,
+        )
+
+    # Create message record
+    message = Message(
+        message_id=str(uuid.uuid4()),
+        thread_id=thread_id,
+        inbox_id=payload.inbox_id,
+        provider_message_id=provider_message_id,
+        direction=MessageDirection.OUTBOUND,
+        text=payload.body,
+        extracted_text=payload.body,  # Already markdown
+        headers={
+            "to": ",".join(payload.to),  # Join list into comma-separated string
+            "subject": payload.subject,
+        },
+        created_at=datetime.now(UTC),
+    )
+    created_message = await storage.create_message(message)
+
+    # Update thread's last_message_at
+    thread = await storage.get_thread(thread_id)
+    if thread:
+        thread.last_message_at = created_message.created_at
+        await storage.update_thread(thread)
+
+    return SendMessageResponse(
+        id=created_message.id,
+        thread_id=thread_id,
+        provider_message_id=provider_message_id,
+        status="sent" if provider_message_id else "pending",
+    )

nornweave/yggdrasil/routes/v1/search.py

@@ -0,0 +1,84 @@
+"""Search endpoint."""
+
+from datetime import datetime  # noqa: TC003 - needed at runtime for Pydantic
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from nornweave.core.interfaces import StorageInterface  # noqa: TC001 - needed at runtime
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+
+
+class SearchRequest(BaseModel):
+    """Search request payload."""
+
+    query: str = Field(..., min_length=1, description="Search query")
+    inbox_id: str = Field(..., description="Inbox to search in")
+    limit: int = Field(default=50, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+
+
+class SearchResultItem(BaseModel):
+    """Individual search result."""
+
+    id: str
+    thread_id: str
+    inbox_id: str
+    direction: str
+    content_clean: str
+    created_at: datetime | None
+    metadata: dict[str, Any]
+
+
+class SearchResponse(BaseModel):
+    """Search response."""
+
+    items: list[SearchResultItem]
+    count: int
+    query: str
+
+
+@router.post("/search", response_model=SearchResponse)
+async def search_messages(
+    payload: SearchRequest,
+    storage: StorageInterface = Depends(get_storage),
+) -> SearchResponse:
+    """Search messages by content.
+
+    Phase 1: Uses SQL ILIKE/LIKE on content_clean and content_raw.
+    Phase 3: Will use vector embeddings for semantic search.
+    """
+    # Verify inbox exists
+    inbox = await storage.get_inbox(payload.inbox_id)
+    if inbox is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {payload.inbox_id} not found",
+        )
+
+    messages = await storage.search_messages(
+        inbox_id=payload.inbox_id,
+        query=payload.query,
+        limit=payload.limit,
+        offset=payload.offset,
+    )
+
+    return SearchResponse(
+        items=[
+            SearchResultItem(
+                id=m.id,
+                thread_id=m.thread_id,
+                inbox_id=m.inbox_id,
+                direction=m.direction.value,
+                content_clean=m.content_clean,
+                created_at=m.created_at,
+                metadata=m.metadata,
+            )
+            for m in messages
+        ],
+        count=len(messages),
+        query=payload.query,
+    )

nornweave/yggdrasil/routes/v1/threads.py

@@ -0,0 +1,142 @@
+"""Thread endpoints."""
+
+from datetime import datetime  # noqa: TC003 - needed at runtime for Pydantic
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+
+from nornweave.core.interfaces import StorageInterface  # noqa: TC001 - needed at runtime
+from nornweave.models.message import MessageDirection
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+
+
+class ThreadMessageResponse(BaseModel):
+    """Message within a thread response (LLM-ready format)."""
+
+    role: str  # "user" for inbound, "assistant" for outbound
+    author: str  # email address from metadata or inbox
+    content: str  # clean markdown content
+    timestamp: datetime | None
+
+
+class ThreadDetailResponse(BaseModel):
+    """Detailed thread response with messages (LLM context format per PRD)."""
+
+    id: str
+    subject: str
+    messages: list[ThreadMessageResponse]
+
+
+class ThreadSummaryResponse(BaseModel):
+    """Thread summary for list views."""
+
+    id: str
+    inbox_id: str
+    subject: str
+    last_message_at: datetime | None
+    participant_hash: str | None
+
+
+class ThreadListResponse(BaseModel):
+    """Response model for thread list."""
+
+    items: list[ThreadSummaryResponse]
+    count: int
+
+
+@router.get("/threads", response_model=ThreadListResponse)
+async def list_threads(
+    inbox_id: str,
+    limit: int = 20,
+    offset: int = 0,
+    storage: StorageInterface = Depends(get_storage),
+) -> ThreadListResponse:
+    """List threads for an inbox, ordered by most recent activity."""
+    # Verify inbox exists
+    inbox = await storage.get_inbox(inbox_id)
+    if inbox is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Inbox {inbox_id} not found",
+        )
+
+    threads = await storage.list_threads_for_inbox(
+        inbox_id,
+        limit=limit,
+        offset=offset,
+    )
+
+    return ThreadListResponse(
+        items=[
+            ThreadSummaryResponse(
+                id=t.id,
+                inbox_id=t.inbox_id,
+                subject=t.subject,
+                last_message_at=t.last_message_at,
+                participant_hash=t.participant_hash,
+            )
+            for t in threads
+        ],
+        count=len(threads),
+    )
+
+
+@router.get("/threads/{thread_id}", response_model=ThreadDetailResponse)
+async def get_thread(
+    thread_id: str,
+    limit: int = 100,
+    offset: int = 0,
+    storage: StorageInterface = Depends(get_storage),
+) -> ThreadDetailResponse:
+    """Get a thread with its messages in LLM-ready format.
+
+    Returns a Markdown-formatted conversation history optimized for context windows,
+    as specified in the PRD.
+    """
+    thread = await storage.get_thread(thread_id)
+    if thread is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Thread {thread_id} not found",
+        )
+
+    # Get messages for the thread
+    messages = await storage.list_messages_for_thread(
+        thread_id,
+        limit=limit,
+        offset=offset,
+    )
+
+    # Get inbox for author mapping
+    inbox = await storage.get_inbox(thread.inbox_id)
+    inbox_email = inbox.email_address if inbox else "unknown@example.com"
+
+    # Convert to LLM-ready format
+    thread_messages = []
+    for msg in messages:
+        # Determine role and author based on direction
+        if msg.direction == MessageDirection.INBOUND:
+            role = "user"
+            # Try to get from address from metadata (headers)
+            metadata = msg.metadata or {}
+            author = metadata.get("from", "unknown@example.com")
+        else:
+            role = "assistant"
+            author = inbox_email
+
+        thread_messages.append(
+            ThreadMessageResponse(
+                role=role,
+                author=str(author),
+                content=msg.content_clean or msg.content_raw,
+                timestamp=msg.created_at,
+            )
+        )
+
+    return ThreadDetailResponse(
+        id=thread.id,
+        subject=thread.subject,
+        messages=thread_messages,
+    )

nornweave/yggdrasil/routes/webhooks/__init__.py

@@ -0,0 +1 @@
+"""Webhook routes (Mailgun, SES, SendGrid)."""

nornweave/yggdrasil/routes/webhooks/mailgun.py

@@ -0,0 +1,136 @@
+"""Mailgun webhook handler."""
+
+import logging
+import uuid
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+
+from nornweave.adapters.mailgun import MailgunAdapter
+from nornweave.core.interfaces import (
+    StorageInterface,  # noqa: TC001 - needed at runtime for FastAPI
+)
+from nornweave.models.message import Message, MessageDirection
+from nornweave.models.thread import Thread
+from nornweave.verdandi.parser import html_to_markdown
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+@router.post("/mailgun", status_code=status.HTTP_200_OK)
+async def mailgun_webhook(
+    request: Request,
+    storage: StorageInterface = Depends(get_storage),
+) -> dict[str, str]:
+    """Handle inbound email webhook from Mailgun.
+
+    Mailgun sends inbound emails as multipart/form-data.
+    This handler:
+    1. Parses the webhook payload
+    2. Finds the inbox by recipient email
+    3. Creates or resolves a thread
+    4. Stores the message
+    """
+    # Parse form data from Mailgun
+    form_data = await request.form()
+    payload = dict(form_data.items())
+
+    logger.info("Received Mailgun webhook for recipient: %s", payload.get("recipient"))
+    logger.debug("Mailgun payload keys: %s", list(payload.keys()))
+
+    # Parse the webhook payload using the Mailgun adapter
+    adapter = MailgunAdapter(api_key="", domain="")  # Keys not needed for parsing
+    try:
+        inbound = adapter.parse_inbound_webhook(payload)
+    except Exception as e:
+        logger.error("Failed to parse Mailgun webhook: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Failed to parse webhook payload: {e}",
+        )
+
+    # Find inbox by recipient email address
+    inbox = await storage.get_inbox_by_email(inbound.to_address)
+    if inbox is None:
+        logger.warning("No inbox found for recipient: %s", inbound.to_address)
+        # Return 200 to prevent Mailgun from retrying, but log the issue
+        return {"status": "no_inbox"}
+
+    logger.info("Found inbox %s for recipient %s", inbox.id, inbound.to_address)
+
+    # Try to find existing thread by Message-ID references (for replies)
+    thread_id: str | None = None
+
+    # Check In-Reply-To header first
+    if inbound.in_reply_to:
+        existing_msg = await storage.get_message_by_provider_id(inbox.id, inbound.in_reply_to)
+        if existing_msg:
+            thread_id = existing_msg.thread_id
+            logger.debug("Found thread via In-Reply-To: %s", thread_id)
+
+    # Check References header
+    if not thread_id and inbound.references:
+        for ref in inbound.references:
+            existing_msg = await storage.get_message_by_provider_id(inbox.id, ref)
+            if existing_msg:
+                thread_id = existing_msg.thread_id
+                logger.debug("Found thread via References: %s", thread_id)
+                break
+
+    # If no thread found, create a new one
+    if thread_id:
+        thread = await storage.get_thread(thread_id)
+    else:
+        # Create new thread
+        new_thread = Thread(
+            thread_id=str(uuid.uuid4()),
+            inbox_id=inbox.id,
+            subject=inbound.subject,
+            timestamp=inbound.timestamp,
+            senders=[inbound.from_address],
+            recipients=[inbound.to_address],
+        )
+        thread = await storage.create_thread(new_thread)
+        thread_id = thread.id
+        logger.info("Created new thread %s for subject: %s", thread_id, inbound.subject)
+
+    # Convert HTML to Markdown for clean content
+    content_clean = inbound.stripped_text or inbound.body_plain
+    if inbound.stripped_html:
+        content_clean = html_to_markdown(inbound.stripped_html)
+    elif inbound.body_html:
+        content_clean = html_to_markdown(inbound.body_html)
+
+    # Create the message
+    message = Message(
+        message_id=str(uuid.uuid4()),
+        thread_id=thread_id,
+        inbox_id=inbox.id,
+        provider_message_id=inbound.message_id,
+        direction=MessageDirection.INBOUND,
+        from_address=inbound.from_address,
+        to=[inbound.to_address],
+        subject=inbound.subject,
+        text=inbound.body_plain,
+        html=inbound.body_html,
+        extracted_text=content_clean,
+        extracted_html=inbound.stripped_html,
+        in_reply_to=inbound.in_reply_to,
+        references=inbound.references if inbound.references else None,
+        headers=inbound.headers,
+        timestamp=inbound.timestamp,
+        created_at=datetime.now(UTC),
+    )
+
+    created_message = await storage.create_message(message)
+    logger.info("Created message %s in thread %s", created_message.id, thread_id)
+
+    # Update thread's last_message_at
+    if thread:
+        thread.last_message_at = created_message.created_at
+        thread.received_timestamp = created_message.created_at
+        await storage.update_thread(thread)
+
+    return {"status": "received", "message_id": created_message.id, "thread_id": thread_id}