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

nornweave/verdandi/llm/__init__.py

@@ -0,0 +1,52 @@
+"""LLM provider abstraction for thread summarization.
+
+Factory function to create the appropriate SummaryProvider based on configuration.
+"""
+
+import logging
+
+from nornweave.core.config import get_settings
+from nornweave.verdandi.llm.base import SummaryProvider, SummaryResult
+
+__all__ = ["SummaryProvider", "SummaryResult", "get_summary_provider"]
+
+logger = logging.getLogger(__name__)
+
+
+def get_summary_provider() -> SummaryProvider | None:
+    """
+    Create and return the appropriate SummaryProvider based on LLM configuration.
+
+    Returns:
+        A SummaryProvider instance if LLM_PROVIDER is configured, None if disabled.
+
+    Raises:
+        ImportError: If the required provider SDK is not installed.
+        ValueError: If LLM_PROVIDER is set but LLM_API_KEY is missing.
+    """
+    settings = get_settings()
+
+    if settings.llm_provider is None:
+        return None
+
+    api_key = settings.llm_api_key
+    model = settings.llm_model
+    prompt = settings.llm_summary_prompt
+
+    if settings.llm_provider == "openai":
+        from nornweave.verdandi.llm.openai import OpenAISummaryProvider
+
+        return OpenAISummaryProvider(api_key=api_key, model=model, prompt=prompt)
+
+    if settings.llm_provider == "anthropic":
+        from nornweave.verdandi.llm.anthropic import AnthropicSummaryProvider
+
+        return AnthropicSummaryProvider(api_key=api_key, model=model, prompt=prompt)
+
+    if settings.llm_provider == "gemini":
+        from nornweave.verdandi.llm.gemini import GeminiSummaryProvider
+
+        return GeminiSummaryProvider(api_key=api_key, model=model, prompt=prompt)
+
+    msg = f"Unknown LLM provider: {settings.llm_provider}"
+    raise ValueError(msg)

nornweave/verdandi/llm/anthropic.py

@@ -0,0 +1,63 @@
+"""Anthropic summarization provider."""
+
+import logging
+
+from nornweave.verdandi.llm.base import SummaryResult
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODEL = "claude-haiku"
+
+
+class AnthropicSummaryProvider:
+    """Summarization provider using Anthropic Messages API."""
+
+    def __init__(self, api_key: str, model: str = "", prompt: str = "") -> None:
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError:
+            msg = (
+                "Anthropic package is required for LLM_PROVIDER='anthropic'. "
+                "Install with: uv add anthropic"
+            )
+            raise ImportError(msg)
+
+        self.client = AsyncAnthropic(api_key=api_key)
+        self.model = model or DEFAULT_MODEL
+        self.prompt = prompt
+
+    async def summarize(self, text: str) -> SummaryResult:
+        """Generate a summary using Anthropic Messages API."""
+        try:
+            from anthropic import APIError
+        except ImportError:
+            APIError = Exception
+
+        try:
+            response = await self.client.messages.create(
+                model=self.model,
+                max_tokens=1024,
+                system=self.prompt,
+                messages=[
+                    {"role": "user", "content": text},
+                ],
+            )
+        except APIError as e:
+            logger.error("Anthropic API error: %s %s", e.status_code, e.message)
+            raise
+
+        summary = ""
+        for block in response.content:
+            if block.type == "text":
+                summary += block.text
+
+        input_tokens = response.usage.input_tokens
+        output_tokens = response.usage.output_tokens
+
+        return SummaryResult(
+            summary=summary.strip(),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=input_tokens + output_tokens,
+            model=response.model or self.model,
+        )

nornweave/verdandi/llm/base.py

@@ -0,0 +1,35 @@
+"""Base protocol and data types for LLM summarization providers."""
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class SummaryResult:
+    """Result of an LLM summarization call."""
+
+    summary: str
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    model: str
+
+
+@runtime_checkable
+class SummaryProvider(Protocol):
+    """Protocol for LLM summarization providers."""
+
+    async def summarize(self, text: str) -> SummaryResult:
+        """
+        Generate a summary of the given text.
+
+        Args:
+            text: The thread text to summarize (formatted conversation).
+
+        Returns:
+            SummaryResult with the generated summary and token usage.
+
+        Raises:
+            Exception: If the provider API call fails.
+        """
+        ...

nornweave/verdandi/llm/gemini.py

@@ -0,0 +1,78 @@
+"""Google Gemini summarization provider using REST API directly.
+
+Uses httpx instead of the google-genai SDK to avoid credential resolution
+conflicts with other Google Cloud libraries (google-auth, google-cloud-storage).
+"""
+
+import logging
+from typing import Any
+
+import httpx
+
+from nornweave.verdandi.llm.base import SummaryResult
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODEL = "gemini-2.0-flash"
+_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+
+class GeminiSummaryProvider:
+    """Summarization provider using Google Generative Language REST API."""
+
+    def __init__(self, api_key: str, model: str = "", prompt: str = "") -> None:
+        self.api_key = api_key
+        self.model = model or DEFAULT_MODEL
+        self.prompt = prompt
+
+    async def summarize(self, text: str) -> SummaryResult:
+        """Generate a summary using the Gemini REST API."""
+        url = f"{_BASE_URL}/models/{self.model}:generateContent"
+
+        payload: dict[str, Any] = {
+            "contents": [{"parts": [{"text": text}]}],
+        }
+        if self.prompt:
+            payload["systemInstruction"] = {"parts": [{"text": self.prompt}]}
+
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            response = await client.post(
+                url,
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "X-goog-api-key": self.api_key,
+                },
+            )
+
+        if response.status_code != 200:
+            body = (
+                response.json()
+                if response.headers.get("content-type", "").startswith("application/json")
+                else {}
+            )
+            error_msg = body.get("error", {}).get("message", response.text[:200])
+            logger.error("Gemini API error %d: %s", response.status_code, error_msg)
+            msg = f"Gemini API returned {response.status_code}: {error_msg}"
+            raise RuntimeError(msg)
+
+        data = response.json()
+        candidates = data.get("candidates", [])
+        summary = ""
+        if candidates:
+            parts = candidates[0].get("content", {}).get("parts", [])
+            summary = "".join(p.get("text", "") for p in parts)
+
+        # Extract token usage from usageMetadata
+        usage = data.get("usageMetadata", {})
+        input_tokens = usage.get("promptTokenCount", 0)
+        output_tokens = usage.get("candidatesTokenCount", 0)
+        total_tokens = usage.get("totalTokenCount", input_tokens + output_tokens)
+
+        return SummaryResult(
+            summary=summary.strip(),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=total_tokens,
+            model=self.model,
+        )

nornweave/verdandi/llm/openai.py

@@ -0,0 +1,60 @@
+"""OpenAI summarization provider."""
+
+import logging
+
+from nornweave.verdandi.llm.base import SummaryResult
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODEL = "gpt-4o-mini"
+
+
+class OpenAISummaryProvider:
+    """Summarization provider using OpenAI Chat Completions API."""
+
+    def __init__(self, api_key: str, model: str = "", prompt: str = "") -> None:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError:
+            msg = (
+                "OpenAI package is required for LLM_PROVIDER='openai'. Install with: uv add openai"
+            )
+            raise ImportError(msg)
+
+        self.client = AsyncOpenAI(api_key=api_key)
+        self.model = model or DEFAULT_MODEL
+        self.prompt = prompt
+
+    async def summarize(self, text: str) -> SummaryResult:
+        """Generate a summary using OpenAI Chat Completions API."""
+        try:
+            from openai import APIError
+        except ImportError:
+            APIError = Exception  # type: ignore[assignment,misc]
+
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.prompt},
+                    {"role": "user", "content": text},
+                ],
+            )
+        except APIError as e:
+            logger.error("OpenAI API error: %s %s", getattr(e, "status_code", None), e.message)
+            raise
+
+        choice = response.choices[0]
+        summary = choice.message.content or ""
+        usage = response.usage
+
+        input_tokens = usage.prompt_tokens if usage else 0
+        output_tokens = usage.completion_tokens if usage else 0
+
+        return SummaryResult(
+            summary=summary.strip(),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=input_tokens + output_tokens,
+            model=response.model or self.model,
+        )

nornweave/verdandi/parser.py

@@ -22,4 +22,5 @@ def html_to_markdown(html: str) -> str:
     h.inline_links = True
     h.protect_links = True
 
-    return h.handle(html).strip()
+    result: str = h.handle(html).strip()
+    return result

nornweave/verdandi/summarize.py

@@ -0,0 +1,231 @@
+"""Thread summarization orchestration.
+
+Generates LLM-powered thread summaries from Talon-cleaned message content.
+Runs as a fire-and-forget post-ingestion hook.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from nornweave.core.config import get_settings
+from nornweave.verdandi.llm import get_summary_provider
+
+if TYPE_CHECKING:
+    from nornweave.core.interfaces import StorageInterface
+    from nornweave.models.message import Message
+
+logger = logging.getLogger(__name__)
+
+# Approximate context window sizes per model family (in tokens).
+# Used for truncation. Conservative estimates at 80% capacity.
+_CONTEXT_WINDOWS: dict[str, int] = {
+    # OpenAI
+    "gpt-4o-mini": 128_000,
+    "gpt-4o": 128_000,
+    "gpt-4-turbo": 128_000,
+    "gpt-3.5-turbo": 16_385,
+    # Anthropic
+    "claude-haiku": 200_000,
+    "claude-sonnet": 200_000,
+    "claude-opus": 200_000,
+    # Gemini
+    "gemini-2.0-flash": 1_000_000,
+    "gemini-2.0-pro": 1_000_000,
+    "gemini-1.5-flash": 1_000_000,
+    "gemini-1.5-pro": 2_000_000,
+}
+_DEFAULT_CONTEXT_WINDOW = 128_000
+# Approximate chars per token for truncation estimation
+_CHARS_PER_TOKEN = 4
+
+
+def prepare_thread_text(messages: list[Message]) -> str:
+    """
+    Prepare thread text for summarization from Talon-cleaned extracted_text.
+
+    Concatenates extracted_text for all messages in chronological order,
+    with [datetime] sender: headers. Falls back to raw text if extracted_text
+    is unavailable. Skips messages with no text content.
+
+    Args:
+        messages: List of messages ordered by timestamp ascending.
+
+    Returns:
+        Formatted conversation text ready for LLM summarization.
+    """
+    sorted_messages = sorted(messages, key=lambda m: m.timestamp or datetime.min)
+    parts: list[str] = []
+
+    for msg in sorted_messages:
+        text = msg.extracted_text or msg.text
+        if not text or not text.strip():
+            continue
+
+        timestamp_str = (
+            msg.timestamp.strftime("%Y-%m-%d %H:%M") if msg.timestamp else "unknown date"
+        )
+        sender = msg.from_address or "unknown"
+        parts.append(f"[{timestamp_str}] {sender}:\n{text.strip()}")
+
+    return "\n\n".join(parts)
+
+
+def truncate_to_context_window(text: str, model: str) -> str:
+    """
+    Truncate thread text to fit within the model's context window.
+
+    Keeps the most recent messages (from the end) that fit within 80% of
+    the model's context window, reserving space for the prompt and response.
+
+    Args:
+        text: The full conversation text.
+        model: The model identifier (used to look up context window size).
+
+    Returns:
+        The text, possibly truncated with a note about earlier messages.
+    """
+    # Find context window for this model (match by prefix for versioned models)
+    context_window = _DEFAULT_CONTEXT_WINDOW
+    for model_prefix, window in _CONTEXT_WINDOWS.items():
+        if model.startswith(model_prefix):
+            context_window = window
+            break
+
+    max_chars = int(context_window * 0.8 * _CHARS_PER_TOKEN)
+
+    if len(text) <= max_chars:
+        return text
+
+    # Split into message blocks and keep from the end
+    blocks = text.split("\n\n")
+    kept: list[str] = []
+    total_chars = 0
+    truncation_note = "[Earlier messages truncated — summary covers the most recent messages]\n\n"
+    available_chars = max_chars - len(truncation_note)
+
+    for block in reversed(blocks):
+        block_len = len(block) + 2  # +2 for the \n\n separator
+        if total_chars + block_len > available_chars:
+            break
+        kept.insert(0, block)
+        total_chars += block_len
+
+    if len(kept) < len(blocks):
+        return truncation_note + "\n\n".join(kept)
+
+    return text
+
+
+async def check_token_budget(storage: StorageInterface) -> bool:
+    """
+    Check if the daily token budget allows another summarization call.
+
+    Args:
+        storage: Storage interface for reading token usage.
+
+    Returns:
+        True if summarization can proceed, False if budget is exhausted.
+    """
+    settings = get_settings()
+    limit = settings.llm_daily_token_limit
+
+    # 0 means unlimited
+    if limit == 0:
+        return True
+
+    today = datetime.now(UTC).date()
+    current_usage = await storage.get_token_usage(today)
+
+    if current_usage >= limit:
+        logger.debug(
+            "Daily token limit reached (%d/%d), skipping summarization", current_usage, limit
+        )
+        return False
+
+    return True
+
+
+async def generate_thread_summary(storage: StorageInterface, thread_id: str) -> None:
+    """
+    Generate or update the LLM summary for a thread.
+
+    Orchestrates: check budget → load messages → prepare text → truncate →
+    call provider → update thread summary → record tokens.
+
+    This function is designed to be called fire-and-forget after message
+    ingestion. Failures are logged and never propagated.
+
+    Args:
+        storage: Storage interface for reading/writing data.
+        thread_id: ID of the thread to summarize.
+    """
+    try:
+        # Step 1: Check if LLM is enabled
+        provider = get_summary_provider()
+        if provider is None:
+            return
+
+        # Step 2: Check daily token budget
+        if not await check_token_budget(storage):
+            return
+
+        # Step 3: Load all messages for the thread
+        messages = await storage.list_messages_for_thread(thread_id, limit=1000)
+        if not messages:
+            return
+
+        # Step 4: Prepare thread text
+        text = prepare_thread_text(messages)
+        if not text.strip():
+            return
+
+        # Step 5: Truncate if needed
+        settings = get_settings()
+        model = settings.llm_model or ""
+        text = truncate_to_context_window(text, model)
+
+        # Step 6: Call the LLM provider
+        result = await provider.summarize(text)
+
+        # If provider didn't report tokens, estimate from character count
+        if result.total_tokens == 0 and (text or result.summary):
+            estimated_input = len(text) // 4
+            estimated_output = len(result.summary) // 4
+            result = type(result)(
+                summary=result.summary,
+                input_tokens=estimated_input,
+                output_tokens=estimated_output,
+                total_tokens=estimated_input + estimated_output,
+                model=result.model,
+            )
+            logger.warning(
+                "Provider did not report token usage for thread %s, estimated %d tokens",
+                thread_id,
+                result.total_tokens,
+            )
+
+        # Step 7: Update thread summary
+        thread = await storage.get_thread(thread_id)
+        if thread is None:
+            logger.warning("Thread %s not found when updating summary", thread_id)
+            return
+
+        thread.summary = result.summary
+        await storage.update_thread(thread)
+
+        # Step 8: Record token usage
+        today = datetime.now(UTC).date()
+        await storage.record_token_usage(today, result.total_tokens)
+
+        logger.info(
+            "Updated summary for thread %s (model=%s, tokens=%d)",
+            thread_id,
+            result.model,
+            result.total_tokens,
+        )
+
+    except Exception as exc:
+        # Provider errors are already logged at ERROR level by the provider itself.
+        # Log a concise warning here without the full traceback to keep logs clean.
+        logger.warning("Failed to generate summary for thread %s: %s", thread_id, exc)

nornweave/yggdrasil/app.py

@@ -52,12 +52,13 @@ def create_app() -> FastAPI:
         return {"status": "ok"}
 
     # Include API routers
-    from nornweave.yggdrasil.routes.v1 import inboxes, messages, search, threads
+    from nornweave.yggdrasil.routes.v1 import attachments, 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"])
+    app.include_router(attachments.router, prefix="/v1", tags=["attachments"])
 
     # Include webhook routers
     from nornweave.yggdrasil.routes.webhooks import mailgun, resend, sendgrid, ses