nornweave 0.1.2__py3-none-any.whl

nornweave/verdandi/threading.py

@@ -0,0 +1,359 @@
+"""Thread grouping logic using JWZ algorithm with Gmail-like heuristics.
+
+This module implements email threading based on:
+1. RFC 5322 headers: Message-ID, In-Reply-To, References
+2. Subject normalization for subject-only matching
+3. Time-window constraints (7-day window for subject matches)
+4. Participant consistency checks (optional)
+
+Reference: https://www.jwz.org/doc/threading.html
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nornweave.core.interfaces import StorageInterface
+
+
+# Subject prefixes to strip for normalization (multi-language)
+REPLY_PREFIXES = re.compile(
+    r"^(?:re|fwd|fw|reply|aw|wg|sv|antw|vs|ref|enc|rv):\s*",
+    re.IGNORECASE,
+)
+
+# Default time window for subject-only matching (Gmail uses ~7 days)
+SUBJECT_MATCH_WINDOW_DAYS = 7
+
+
+@dataclass
+class ThreadResolutionResult:
+    """Result of thread resolution."""
+
+    thread_id: str
+    is_new_thread: bool
+    matched_by: str  # "references", "in_reply_to", "subject", or "new"
+
+
+def normalize_subject(subject: str) -> str:
+    """
+    Normalize subject for thread matching.
+
+    Strips common reply/forward prefixes in multiple languages,
+    collapses whitespace, and lowercases for comparison.
+
+    Examples:
+        "Re: Hello" -> "hello"
+        "Fwd: Re: Meeting" -> "meeting"
+        "AW: Anfrage" -> "anfrage" (German)
+        "SV: Förfrågan" -> "förfrågan" (Swedish)
+
+    Args:
+        subject: Original email subject
+
+    Returns:
+        Normalized subject string for comparison
+    """
+    if not subject:
+        return ""
+
+    normalized = subject.strip()
+
+    # Iteratively strip reply/forward prefixes
+    while True:
+        result = REPLY_PREFIXES.sub("", normalized, count=1).strip()
+        if result == normalized:
+            break
+        normalized = result
+
+    # Collapse whitespace and lowercase
+    normalized = " ".join(normalized.split()).lower()
+
+    return normalized
+
+
+def compute_participant_hash(
+    from_address: str,
+    to_addresses: list[str],
+    cc_addresses: list[str] | None = None,
+) -> str:
+    """
+    Compute a hash of thread participants for grouping.
+
+    This creates a canonical representation of participants
+    that can be used as a secondary threading signal.
+
+    Args:
+        from_address: Sender email address
+        to_addresses: List of recipient addresses
+        cc_addresses: Optional list of CC addresses
+
+    Returns:
+        SHA-256 hash of sorted, normalized participants
+    """
+    # Normalize and collect all addresses
+    participants = set()
+
+    def normalize_addr(addr: str) -> str:
+        # Extract just the email part, lowercase
+        addr = addr.lower().strip()
+        # Handle "Name <email>" format
+        if "<" in addr and ">" in addr:
+            addr = addr.split("<")[1].split(">")[0]
+        return addr
+
+    participants.add(normalize_addr(from_address))
+    for addr in to_addresses:
+        participants.add(normalize_addr(addr))
+    if cc_addresses:
+        for addr in cc_addresses:
+            participants.add(normalize_addr(addr))
+
+    # Sort for consistent hashing
+    sorted_participants = sorted(participants)
+    combined = ",".join(sorted_participants)
+
+    return hashlib.sha256(combined.encode()).hexdigest()[:16]
+
+
+def parse_references_header(references: str | None) -> list[str]:
+    """
+    Parse the References header into a list of Message-IDs.
+
+    References header contains space-separated Message-IDs:
+    "<id1@host> <id2@host> <id3@host>"
+
+    Args:
+        references: Raw References header value
+
+    Returns:
+        List of Message-ID strings
+    """
+    if not references:
+        return []
+
+    # Split by whitespace and filter empty
+    refs = [ref.strip() for ref in references.split() if ref.strip()]
+
+    # Validate that each looks like a Message-ID (contains @, wrapped in <>)
+    valid_refs = []
+    for ref in refs:
+        if "@" in ref:
+            # Normalize: ensure angle brackets
+            if not ref.startswith("<"):
+                ref = "<" + ref
+            if not ref.endswith(">"):
+                ref = ref + ">"
+            valid_refs.append(ref)
+
+    return valid_refs
+
+
+def normalize_message_id(message_id: str | None) -> str | None:
+    """
+    Normalize a Message-ID for consistent storage and lookup.
+
+    Args:
+        message_id: Raw Message-ID value
+
+    Returns:
+        Normalized Message-ID with angle brackets, or None
+    """
+    if not message_id:
+        return None
+
+    mid = message_id.strip()
+    if not mid:
+        return None
+
+    # Ensure angle brackets
+    if not mid.startswith("<"):
+        mid = "<" + mid
+    if not mid.endswith(">"):
+        mid = mid + ">"
+
+    return mid
+
+
+async def resolve_thread(
+    storage: StorageInterface,
+    inbox_id: str,
+    *,
+    message_id: str | None = None,  # noqa: ARG001 - reserved for future use
+    in_reply_to: str | None = None,
+    references: list[str] | None = None,
+    subject: str = "",
+    timestamp: datetime | None = None,
+    from_address: str = "",  # noqa: ARG001 - reserved for future use
+    to_addresses: list[str] | None = None,  # noqa: ARG001 - reserved for future use
+) -> ThreadResolutionResult:
+    """
+    Resolve thread ID using JWZ algorithm with Gmail-like heuristics.
+
+    Algorithm:
+    1. If References exist, find matching parent message (last ref first)
+    2. If In-Reply-To exists and no References match, try In-Reply-To
+    3. If neither header matches, try subject-only matching within 7-day window
+    4. If no match, create new thread
+
+    Args:
+        storage: Storage interface for lookups
+        inbox_id: Inbox to search within
+        message_id: This message's Message-ID (for storing)
+        in_reply_to: In-Reply-To header (parent Message-ID)
+        references: List of Message-IDs from References header
+        subject: Email subject
+        timestamp: Message timestamp (for subject matching window)
+        from_address: Sender address (for participant hash)
+        to_addresses: Recipient addresses (for participant hash)
+
+    Returns:
+        ThreadResolutionResult with thread_id and metadata
+    """
+    import uuid
+
+    timestamp = timestamp or datetime.utcnow()
+
+    # Priority 1: Check References header (most reliable)
+    if references:
+        # Check references in reverse order (most recent parent first)
+        for ref in reversed(references):
+            normalized_ref = normalize_message_id(ref)
+            if normalized_ref:
+                parent_msg = await storage.get_message_by_provider_id(inbox_id, normalized_ref)
+                if parent_msg:
+                    return ThreadResolutionResult(
+                        thread_id=parent_msg.thread_id,
+                        is_new_thread=False,
+                        matched_by="references",
+                    )
+
+    # Priority 2: Check In-Reply-To header
+    if in_reply_to:
+        in_reply_to = normalize_message_id(in_reply_to)
+        if in_reply_to:
+            parent_msg = await storage.get_message_by_provider_id(inbox_id, in_reply_to)
+            if parent_msg:
+                return ThreadResolutionResult(
+                    thread_id=parent_msg.thread_id,
+                    is_new_thread=False,
+                    matched_by="in_reply_to",
+                )
+
+    # Priority 3: Subject-only matching within time window
+    if subject:
+        normalized = normalize_subject(subject)
+        if normalized:
+            # Only match subjects within 7-day window
+            since_time = timestamp - timedelta(days=SUBJECT_MATCH_WINDOW_DAYS)
+            thread = await storage.get_thread_by_subject(inbox_id, normalized, since=since_time)
+            if thread:
+                return ThreadResolutionResult(
+                    thread_id=thread.thread_id,
+                    is_new_thread=False,
+                    matched_by="subject",
+                )
+
+    # No match found: create new thread
+    new_thread_id = str(uuid.uuid4())
+    return ThreadResolutionResult(
+        thread_id=new_thread_id,
+        is_new_thread=True,
+        matched_by="new",
+    )
+
+
+def resolve_thread_id(
+    _message_id: str | None,
+    _references: str | None,
+    _in_reply_to: str | None,
+    _subject: str,
+) -> str | None:
+    """
+    Legacy synchronous placeholder for thread resolution.
+
+    Deprecated: Use async resolve_thread() instead.
+    """
+    return None
+
+
+def build_references_chain(
+    parent_references: list[str] | None,
+    parent_message_id: str | None,
+    *,
+    max_length: int = 20,
+) -> list[str]:
+    """
+    Build References chain for a reply message.
+
+    Per RFC 5322, the References header should contain the Message-IDs
+    of all ancestor messages in the thread. To prevent unbounded growth,
+    we limit to the most recent ~20 entries.
+
+    Args:
+        parent_references: References from the parent message
+        parent_message_id: Message-ID of the parent message
+        max_length: Maximum number of references to include
+
+    Returns:
+        List of Message-IDs for the new References header
+    """
+    refs: list[str] = []
+
+    # Start with existing references
+    if parent_references:
+        refs.extend(parent_references)
+
+    # Add parent's Message-ID
+    if parent_message_id:
+        parent_mid = normalize_message_id(parent_message_id)
+        if parent_mid and parent_mid not in refs:
+            refs.append(parent_mid)
+
+    # Trim to max length (keep most recent)
+    if len(refs) > max_length:
+        refs = refs[-max_length:]
+
+    return refs
+
+
+def should_thread_together(
+    subject1: str,
+    subject2: str,
+    time_diff: timedelta | None = None,
+) -> bool:
+    """
+    Determine if two messages should be in the same thread based on subject.
+
+    Uses normalized subject comparison and optional time constraint.
+
+    Args:
+        subject1: First message subject
+        subject2: Second message subject
+        time_diff: Time difference between messages (optional)
+
+    Returns:
+        True if messages should be threaded together
+    """
+    # Normalize both subjects
+    norm1 = normalize_subject(subject1)
+    norm2 = normalize_subject(subject2)
+
+    # Empty subjects never match
+    if not norm1 or not norm2:
+        return False
+
+    # Subjects must match
+    if norm1 != norm2:
+        return False
+
+    # Check time window if provided
+    if time_diff is not None:
+        max_diff = timedelta(days=SUBJECT_MATCH_WINDOW_DAYS)
+        if abs(time_diff) > max_diff:
+            return False
+
+    return True

nornweave/yggdrasil/__init__.py

@@ -0,0 +1 @@
+"""Yggdrasil: API gateway and router."""

nornweave/yggdrasil/app.py

@@ -0,0 +1,86 @@
+"""FastAPI application factory (Yggdrasil)."""
+
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from nornweave import __version__
+from nornweave.core.config import get_settings
+from nornweave.yggdrasil.dependencies import close_database, init_database
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+    """Application lifespan: initialize and close database connections."""
+    settings = get_settings()
+    await init_database(settings)
+    yield
+    await close_database()
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    settings = get_settings()
+
+    app = FastAPI(
+        title="NornWeave",
+        description="Open-source Inbox-as-a-Service API for AI Agents",
+        version=__version__,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        lifespan=lifespan,
+    )
+
+    # CORS middleware
+    origins = [o.strip() for o in settings.cors_origins.split(",") if o.strip()]
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins if origins else ["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Health check endpoint
+    @app.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    # Include API routers
+    from nornweave.yggdrasil.routes.v1 import inboxes, messages, search, threads
+
+    app.include_router(inboxes.router, prefix="/v1", tags=["inboxes"])
+    app.include_router(threads.router, prefix="/v1", tags=["threads"])
+    app.include_router(messages.router, prefix="/v1", tags=["messages"])
+    app.include_router(search.router, prefix="/v1", tags=["search"])
+
+    # Include webhook routers
+    from nornweave.yggdrasil.routes.webhooks import mailgun, resend, sendgrid, ses
+
+    app.include_router(mailgun.router, prefix="/webhooks", tags=["webhooks"])
+    app.include_router(sendgrid.router, prefix="/webhooks", tags=["webhooks"])
+    app.include_router(ses.router, prefix="/webhooks", tags=["webhooks"])
+    app.include_router(resend.router, prefix="/webhooks", tags=["webhooks"])
+
+    return app
+
+
+app = create_app()
+
+
+def main() -> None:
+    """CLI entry point: run uvicorn."""
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "nornweave.yggdrasil.app:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.environment == "development",
+    )

nornweave/yggdrasil/dependencies.py

@@ -0,0 +1,190 @@
+"""Dependency injection (storage, provider)."""
+
+from collections.abc import AsyncGenerator  # noqa: TC003 - needed at runtime
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import Depends, Request
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from nornweave.core.config import Settings, get_settings
+from nornweave.core.interfaces import (  # noqa: TC001 - needed at runtime for FastAPI
+    EmailProvider,
+    StorageInterface,
+)
+
+# -----------------------------------------------------------------------------
+# Database engine management
+# -----------------------------------------------------------------------------
+_engine: AsyncEngine | None = None
+_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+def get_database_url(settings: Settings) -> str:
+    """Get database URL from settings with validation."""
+    url = settings.database_url
+
+    if not url:
+        if settings.db_driver == "sqlite":
+            # Default SQLite path for local development
+            url = "sqlite+aiosqlite:///./nornweave.db"
+        else:
+            raise ValueError("DATABASE_URL must be set for PostgreSQL")
+
+    # Validate URL matches driver
+    if settings.db_driver == "postgres":
+        if not url.startswith("postgresql"):
+            raise ValueError(
+                f"DATABASE_URL must start with 'postgresql' for postgres driver, got: {url}"
+            )
+        # Ensure async driver
+        if "asyncpg" not in url:
+            url = url.replace("postgresql://", "postgresql+asyncpg://")
+    elif settings.db_driver == "sqlite":
+        if not url.startswith("sqlite"):
+            raise ValueError(f"DATABASE_URL must start with 'sqlite' for sqlite driver, got: {url}")
+        # Ensure async driver
+        if "aiosqlite" not in url:
+            url = url.replace("sqlite://", "sqlite+aiosqlite://")
+
+    return url
+
+
+async def init_database(settings: Settings | None = None) -> None:
+    """Initialize database engine and session factory."""
+    global _engine, _session_factory
+
+    if settings is None:
+        settings = get_settings()
+
+    url = get_database_url(settings)
+
+    # Engine configuration
+    engine_kwargs: dict[str, Any] = {
+        "echo": settings.environment == "development" and settings.log_level == "DEBUG",
+    }
+
+    # SQLite-specific settings
+    if settings.db_driver == "sqlite":
+        engine_kwargs["connect_args"] = {"check_same_thread": False}
+
+    _engine = create_async_engine(url, **engine_kwargs)
+    _session_factory = async_sessionmaker(
+        _engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+    # Enable foreign keys for SQLite
+    if settings.db_driver == "sqlite":
+        from sqlalchemy import event
+        from sqlalchemy.engine import Engine
+
+        @event.listens_for(Engine, "connect")
+        def set_sqlite_pragma(dbapi_conn: Any, _connection_record: Any) -> None:
+            cursor = dbapi_conn.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+
+async def close_database() -> None:
+    """Close database engine."""
+    global _engine, _session_factory
+
+    if _engine is not None:
+        await _engine.dispose()
+        _engine = None
+        _session_factory = None
+
+
+@asynccontextmanager
+async def get_session() -> AsyncGenerator[AsyncSession]:
+    """Get a database session (context manager)."""
+    if _session_factory is None:
+        raise RuntimeError("Database not initialized. Call init_database() first.")
+
+    async with _session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+# -----------------------------------------------------------------------------
+# FastAPI Dependencies
+# -----------------------------------------------------------------------------
+async def get_db_session(_request: Request) -> AsyncGenerator[AsyncSession]:
+    """FastAPI dependency to get a database session."""
+    if _session_factory is None:
+        raise RuntimeError("Database not initialized")
+
+    async with _session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_storage(
+    session: AsyncSession = Depends(get_db_session),
+    settings: Settings = Depends(get_settings),
+) -> StorageInterface:
+    """FastAPI dependency to get the configured storage adapter."""
+    if settings.db_driver == "postgres":
+        try:
+            from nornweave.urdr.adapters.postgres import PostgresAdapter
+        except ImportError as e:
+            raise ImportError(
+                "PostgreSQL support requires additional dependencies. "
+                "Install with: pip install nornweave[postgres]"
+            ) from e
+        return PostgresAdapter(session)
+    elif settings.db_driver == "sqlite":
+        from nornweave.urdr.adapters.sqlite import SQLiteAdapter
+
+        return SQLiteAdapter(session)
+    else:
+        raise ValueError(f"Unknown db_driver: {settings.db_driver}")
+
+
+async def get_email_provider(
+    settings: Settings = Depends(get_settings),
+) -> EmailProvider:
+    """FastAPI dependency to get the configured email provider."""
+    # Import here to avoid circular imports
+    from nornweave.adapters.mailgun import MailgunAdapter
+    from nornweave.adapters.resend import ResendAdapter
+    from nornweave.adapters.sendgrid import SendGridAdapter
+    from nornweave.adapters.ses import SESAdapter
+
+    provider = settings.email_provider
+
+    if provider == "mailgun":
+        return MailgunAdapter(
+            api_key=settings.mailgun_api_key,
+            domain=settings.mailgun_domain,
+        )
+    elif provider == "sendgrid":
+        return SendGridAdapter(api_key=settings.sendgrid_api_key)
+    elif provider == "ses":
+        return SESAdapter(
+            access_key_id=settings.aws_access_key_id,
+            secret_access_key=settings.aws_secret_access_key,
+            region=settings.aws_region,
+        )
+    elif provider == "resend":
+        return ResendAdapter(
+            api_key=settings.resend_api_key,
+            webhook_secret=settings.resend_webhook_secret,
+        )
+    else:
+        raise ValueError(f"Unknown email_provider: {provider}")

nornweave/yggdrasil/middleware/__init__.py

@@ -0,0 +1 @@
+"""Middleware: auth, logging."""

nornweave/yggdrasil/middleware/auth.py

@@ -0,0 +1 @@
+"""API key authentication middleware. Placeholder."""

nornweave/yggdrasil/middleware/logging.py

@@ -0,0 +1 @@
+"""Request/response logging middleware. Placeholder."""

nornweave/yggdrasil/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes."""

nornweave/yggdrasil/routes/v1/__init__.py

@@ -0,0 +1 @@
+"""REST API v1 routes."""