nornweave 0.1.2__py3-none-any.whl

nornweave/cli.py

@@ -0,0 +1,186 @@
+"""NornWeave CLI.
+
+Provides commands for running the API server and MCP server.
+"""
+
+import sys
+from typing import Literal
+
+import click
+
+
+@click.group()
+@click.version_option()
+def cli() -> None:
+    """NornWeave - Inbox-as-a-Service API for AI Agents.
+
+    Run the API server or MCP server for AI agent integration.
+    """
+
+
+@cli.command("api")
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    help="Host to bind to",
+    show_default=True,
+)
+@click.option(
+    "--port",
+    default=8000,
+    type=int,
+    help="Port to listen on",
+    show_default=True,
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    help="Enable auto-reload for development",
+)
+def api_cmd(host: str, port: int, reload: bool) -> None:
+    """Run the NornWeave REST API server.
+
+    This starts the FastAPI server that handles webhooks, REST API requests,
+    and serves as the backend for the MCP server.
+
+    Examples:
+
+        nornweave api
+
+        nornweave api --port 9000
+
+        nornweave api --reload
+    """
+    import uvicorn
+
+    uvicorn.run(
+        "nornweave.yggdrasil.app:app",
+        host=host,
+        port=port,
+        reload=reload,
+    )
+
+
+@cli.command("mcp")
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "sse", "http"]),
+    default="stdio",
+    help="MCP transport type",
+    show_default=True,
+)
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    help="Host to bind to (SSE/HTTP only)",
+    show_default=True,
+)
+@click.option(
+    "--port",
+    default=3000,
+    type=int,
+    help="Port to listen on (SSE/HTTP only)",
+    show_default=True,
+)
+@click.option(
+    "--api-url",
+    envvar="NORNWEAVE_API_URL",
+    default="http://localhost:8000",
+    help="NornWeave API URL",
+    show_default=True,
+)
+def mcp_cmd(
+    transport: Literal["stdio", "sse", "http"],
+    host: str,
+    port: int,
+    api_url: str,
+) -> None:
+    """Run the NornWeave MCP server.
+
+    This starts the Model Context Protocol server that allows AI agents
+    (Claude, Cursor, LangChain) to interact with email.
+
+    Transports:
+
+        stdio   - Standard input/output (default). For Claude Desktop, Cursor.
+
+        sse     - Server-Sent Events. For web-based MCP clients.
+
+        http    - Streamable HTTP. For cloud deployments, LangChain.
+
+    Environment Variables:
+
+        NORNWEAVE_API_URL   - NornWeave API base URL (default: http://localhost:8000)
+
+        NORNWEAVE_API_KEY   - API key for authentication (optional)
+
+    Examples:
+
+        nornweave mcp
+
+        nornweave mcp --transport sse --port 3000
+
+        nornweave mcp --transport http --host 127.0.0.1 --port 8080
+
+        nornweave mcp --api-url http://api.example.com:8000
+
+    Claude Desktop / Cursor Configuration:
+
+        {
+          "mcpServers": {
+            "nornweave": {
+              "command": "nornweave",
+              "args": ["mcp"]
+            }
+          }
+        }
+    """
+    # Set API URL in environment for the MCP server to pick up
+    import os
+
+    os.environ["NORNWEAVE_API_URL"] = api_url
+
+    try:
+        from nornweave.huginn.server import serve
+    except ImportError as e:
+        click.echo(
+            "Error: MCP dependencies not installed. Install with: pip install nornweave[mcp]",
+            err=True,
+        )
+        click.echo(f"Details: {e}", err=True)
+        sys.exit(1)
+
+    if transport == "stdio":
+        click.echo("Starting MCP server (stdio transport)...", err=True)
+        click.echo(f"API URL: {api_url}", err=True)
+    else:
+        click.echo(f"Starting MCP server ({transport} transport)...", err=True)
+        click.echo(f"Listening on {host}:{port}", err=True)
+        click.echo(f"API URL: {api_url}", err=True)
+
+    serve(transport=transport, host=host, port=port)
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    cli()
+
+
+# Legacy entry point for backwards compatibility
+def run_api() -> None:
+    """Run the API server (legacy entry point)."""
+    import uvicorn
+
+    from nornweave.core.config import get_settings
+
+    settings = get_settings()
+    uvicorn.run(
+        "nornweave.yggdrasil.app:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.environment == "development",
+    )
+
+
+if __name__ == "__main__":
+    main()

nornweave/core/__init__.py

@@ -0,0 +1,26 @@
+"""Core interfaces, config, and utilities."""
+
+from nornweave.core.config import Settings, get_settings
+from nornweave.core.exceptions import (
+    NornWeaveError,
+    NotFoundError,
+    ProviderError,
+    ValidationError,
+)
+from nornweave.core.interfaces import (
+    EmailProvider,
+    InboundMessage,
+    StorageInterface,
+)
+
+__all__ = [
+    "EmailProvider",
+    "InboundMessage",
+    "NornWeaveError",
+    "NotFoundError",
+    "ProviderError",
+    "Settings",
+    "StorageInterface",
+    "ValidationError",
+    "get_settings",
+]

nornweave/core/config.py

@@ -0,0 +1,172 @@
+"""Application configuration (Pydantic settings)."""
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """NornWeave configuration from environment."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Storage (Urdr)  # noqa: ERA001
+    db_driver: Literal["postgres", "sqlite"] = Field(default="postgres", alias="DB_DRIVER")
+    database_url: str = Field(default="", alias="DATABASE_URL")
+
+    # Email provider
+    email_provider: Literal["mailgun", "ses", "sendgrid", "resend"] = Field(
+        default="mailgun", alias="EMAIL_PROVIDER"
+    )
+    email_domain: str = Field(default="", alias="EMAIL_DOMAIN")
+
+    # Provider-specific (filled per provider)
+    mailgun_api_key: str = Field(default="", alias="MAILGUN_API_KEY")
+    mailgun_domain: str = Field(default="", alias="MAILGUN_DOMAIN")
+    sendgrid_api_key: str = Field(default="", alias="SENDGRID_API_KEY")
+    resend_api_key: str = Field(default="", alias="RESEND_API_KEY")
+    resend_webhook_secret: str = Field(default="", alias="RESEND_WEBHOOK_SECRET")
+    aws_access_key_id: str = Field(default="", alias="AWS_ACCESS_KEY_ID")
+    aws_secret_access_key: str = Field(default="", alias="AWS_SECRET_ACCESS_KEY")
+    aws_region: str = Field(default="us-east-1", alias="AWS_REGION")
+
+    # API security
+    api_key: str = Field(default="", alias="API_KEY")
+    cors_origins: str = Field(default="*", alias="CORS_ORIGINS")
+
+    # Server
+    host: str = Field(default="0.0.0.0", alias="HOST")
+    port: int = Field(default=8000, alias="PORT")
+    environment: Literal["development", "staging", "production"] = Field(
+        default="development", alias="ENVIRONMENT"
+    )
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = Field(
+        default="INFO", alias="LOG_LEVEL"
+    )
+
+    # Phase 3
+    redis_url: str = Field(default="redis://localhost:6379/0", alias="REDIS_URL")
+    openai_api_key: str = Field(default="", alias="OPENAI_API_KEY")
+    webhook_secret: str = Field(default="", alias="WEBHOOK_SECRET")
+
+    # -------------------------------------------------------------------------
+    # Attachment Storage Configuration
+    # -------------------------------------------------------------------------
+    # Backend selection: "local", "s3", "gcs", "database"
+    attachment_storage_backend: Literal["local", "s3", "gcs", "database"] = Field(
+        default="local",
+        alias="ATTACHMENT_STORAGE_BACKEND",
+        description="Storage backend for attachments",
+    )
+
+    # Local filesystem settings
+    attachment_local_path: str = Field(
+        default="./data/attachments",
+        alias="ATTACHMENT_LOCAL_PATH",
+        description="Base path for local filesystem storage",
+    )
+    attachment_serve_url_prefix: str = Field(
+        default="/v1/attachments",
+        alias="ATTACHMENT_SERVE_URL_PREFIX",
+        description="URL prefix for attachment downloads",
+    )
+
+    # S3 settings
+    attachment_s3_bucket: str | None = Field(
+        default=None,
+        alias="ATTACHMENT_S3_BUCKET",
+        description="S3 bucket for attachment storage",
+    )
+    attachment_s3_prefix: str = Field(
+        default="attachments",
+        alias="ATTACHMENT_S3_PREFIX",
+        description="S3 key prefix for attachments",
+    )
+    attachment_s3_region: str = Field(
+        default="us-east-1",
+        alias="ATTACHMENT_S3_REGION",
+        description="AWS region for S3 bucket",
+    )
+    attachment_s3_access_key: str | None = Field(
+        default=None,
+        alias="ATTACHMENT_S3_ACCESS_KEY",
+        description="AWS access key (uses IAM role if not set)",
+    )
+    attachment_s3_secret_key: str | None = Field(
+        default=None,
+        alias="ATTACHMENT_S3_SECRET_KEY",
+        description="AWS secret key (uses IAM role if not set)",
+    )
+
+    # GCS settings
+    attachment_gcs_bucket: str | None = Field(
+        default=None,
+        alias="ATTACHMENT_GCS_BUCKET",
+        description="GCS bucket for attachment storage",
+    )
+    attachment_gcs_prefix: str = Field(
+        default="attachments",
+        alias="ATTACHMENT_GCS_PREFIX",
+        description="GCS blob prefix for attachments",
+    )
+    attachment_gcs_credentials_path: str | None = Field(
+        default=None,
+        alias="ATTACHMENT_GCS_CREDENTIALS_PATH",
+        description="Path to GCS service account JSON (uses ADC if not set)",
+    )
+
+    # Download URL settings
+    attachment_url_expiry_seconds: int = Field(
+        default=3600,
+        alias="ATTACHMENT_URL_EXPIRY_SECONDS",
+        description="Default expiry time for download URLs in seconds",
+    )
+
+    # Size limits
+    attachment_max_size_mb: int = Field(
+        default=25,
+        alias="ATTACHMENT_MAX_SIZE_MB",
+        description="Maximum size for single attachment in MB",
+    )
+    attachment_max_total_size_mb: int = Field(
+        default=35,
+        alias="ATTACHMENT_MAX_TOTAL_SIZE_MB",
+        description="Maximum total size for all attachments in MB",
+    )
+    attachment_max_count: int = Field(
+        default=20,
+        alias="ATTACHMENT_MAX_COUNT",
+        description="Maximum number of attachments per message",
+    )
+
+    # -------------------------------------------------------------------------
+    # Content Extraction Configuration (Talon)
+    # -------------------------------------------------------------------------
+    talon_use_ml_signature: bool = Field(
+        default=True,
+        alias="TALON_USE_ML_SIGNATURE",
+        description="Use ML-based signature extraction (more accurate)",
+    )
+    message_preview_max_length: int = Field(
+        default=100,
+        alias="MESSAGE_PREVIEW_MAX_LENGTH",
+        description="Maximum length for message preview text",
+    )
+    extraction_fallback_to_original: bool = Field(
+        default=True,
+        alias="EXTRACTION_FALLBACK_TO_ORIGINAL",
+        description="Return original content if extraction fails",
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return cached settings instance."""
+    return Settings()

nornweave/core/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exception hierarchy for NornWeave."""
+
+
+class NornWeaveError(Exception):
+    """Base exception for all NornWeave errors."""
+
+    pass
+
+
+class NotFoundError(NornWeaveError):
+    """Resource not found (inbox, thread, message)."""
+
+    pass
+
+
+class ValidationError(NornWeaveError):
+    """Invalid input or state."""
+
+    pass
+
+
+class ProviderError(NornWeaveError):
+    """Email or storage provider error."""
+
+    pass