Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

16.2 KB
Raw Blame
"""
Queue notification helpers for the notification system.

Provides helper functions for sending queue-related notifications
to keep the queue manager focused on queue logic.
"""

from typing import Any, Dict, Optional
from loguru import logger
from sqlalchemy.orm import Session

from .exceptions import RateLimitError
from .manager import NotificationManager, NotificationResult
from .templates import EventType


def _format_reason(result: Any) -> str:
    """Render a ``send_notification`` outcome as ``"(reason: detail)"``,
    falling back to ``bool(result)`` so legacy mocks / older callers that
    still return a bare ``True``/``False`` keep working.
    """
    if isinstance(result, NotificationResult):
        if result.detail:
            return f"({result.reason.value}: {result.detail})"
        return f"({result.reason.value})"
    return f"({'sent' if bool(result) else 'dropped'})"


def send_queue_notification(
    username: str,
    research_id: str,
    query: str,
    settings_snapshot: Dict[str, Any],
    position: Optional[int] = None,
) -> bool:
    """
    Send a research queued notification.

    Args:
        username: User who owns the research
        research_id: UUID of the research
        query: Research query string
        settings_snapshot: Settings snapshot for thread-safe access
        position: Queue position (optional)

    Returns:
        True if notification was sent successfully, False otherwise.
        Returned as ``bool`` for backward compatibility; the precise
        reason for a falsy return is logged via ``NotificationResult``.
    """
    try:
        notification_manager = NotificationManager(
            settings_snapshot=settings_snapshot, user_id=username
        )

        # Build notification context
        context: Dict[str, Any] = {
            "query": query,
            "research_id": research_id,
        }

        if position is not None:
            context["position"] = position
            context["wait_time"] = (
                "Unknown"  # Could estimate based on active researches
            )

        result = notification_manager.send_notification(
            event_type=EventType.RESEARCH_QUEUED,
            context=context,
        )
        if not result:
            # DEBUG on purpose: notifications.on_research_queued defaults
            # to off, so this drop is the steady state for every queued
            # research — WARNING here would spam once per submission.
            # Actionable causes (server gate, delivery failure) already
            # WARN inside send_notification itself.
            logger.debug(
                f"Queue notification not sent for {research_id} "
                f"{_format_reason(result)}"
            )
        return bool(getattr(result, "sent", result))

    except RateLimitError:
        logger.warning(
            f"Rate limited sending queued notification for {research_id}"
        )
        return False
    except Exception:
        logger.warning(f"Failed to send queued notification for {research_id}")
        return False


def send_queue_failed_notification(
    username: str,
    research_id: str,
    query: str,
    error_message: Optional[str] = None,
    settings_snapshot: Optional[Dict[str, Any]] = None,
) -> bool:
    """
    Send a research failed notification from queue operations.

    Args:
        username: User who owns the research
        research_id: UUID of the research
        query: Research query string
        error_message: Optional error message
        settings_snapshot: Settings snapshot for thread-safe access

    Returns:
        True if notification was sent successfully, False otherwise.
        Returned as ``bool`` for backward compatibility; the precise
        reason for a falsy return is logged via ``NotificationResult``.
    """
    if not settings_snapshot:
        logger.debug("No settings snapshot provided for failed notification")
        return False

    try:
        notification_manager = NotificationManager(
            settings_snapshot=settings_snapshot, user_id=username
        )

        # Build notification context
        context = {
            "query": query,
            "research_id": research_id,
        }

        if error_message:
            context["error"] = error_message

        result = notification_manager.send_notification(
            event_type=EventType.RESEARCH_FAILED,
            context=context,
        )
        if not result:
            # DEBUG on purpose: the from_session wrapper around this
            # helper already emits its own WARNING on a falsy return, so
            # a WARNING here would double-log every drop. The reason
            # string is still available at debug level.
            logger.debug(
                f"Failed-notification not sent for {research_id} "
                f"{_format_reason(result)}"
            )
        return bool(getattr(result, "sent", result))

    except RateLimitError:
        logger.warning(
            f"Rate limited sending failed notification for {research_id}"
        )
        return False
    except Exception:
        logger.warning(f"Failed to send failed notification for {research_id}")
        return False


def send_queue_failed_notification_from_session(
    username: str,
    research_id: str,
    query: str,
    error_message: str,
    db_session: Session,
) -> None:
    """
    Send a research failed notification, fetching settings from db_session.

    This is a convenience wrapper for the queue processor that handles
    settings snapshot retrieval, logging, and error handling internally.
    All notification logic is contained within this function.

    Args:
        username: User who owns the research
        research_id: UUID of the research
        query: Research query string
        error_message: Error message to include in notification
        db_session: Database session to fetch settings from
    """
    try:
        from ..settings import SettingsManager

        # Get settings snapshot from database session
        settings_manager = SettingsManager(db_session)
        settings_snapshot = settings_manager.get_settings_snapshot()

        # Send notification (handles RateLimitError internally, returns False)
        success = send_queue_failed_notification(
            username=username,
            research_id=research_id,
            query=query,
            error_message=error_message,
            settings_snapshot=settings_snapshot,
        )

        if success:
            logger.info(f"Sent failure notification for research {research_id}")
        else:
            logger.warning(
                f"Failed to send failure notification for {research_id} (not sent)"
            )
    except Exception:
        logger.exception(
            f"Failed to send failure notification for {research_id}"
        )


def send_research_completed_notification_from_session(
    username: str,
    research_id: str,
    db_session: Session,
) -> None:
    """
    Send research completed notification with summary and URL.

    This is a convenience wrapper for the queue processor that handles
    all notification logic for completed research, including:
    - Research database lookup
    - Report content retrieval
    - URL building
    - Context building with summary
    - All logging and error handling

    Args:
        username: User who owns the research
        research_id: UUID of the research
        db_session: Database session to fetch research and settings from
    """
    try:
        logger.info(
            f"Starting completed notification process for research {research_id}, "
            f"user {username}"
        )

        # Import here to avoid circular dependencies
        from ..database.models import ResearchHistory
        from ..settings import SettingsManager
        from .manager import NotificationManager
        from .url_builder import build_notification_url

        # Get research details for notification
        research = (
            db_session.query(ResearchHistory).filter_by(id=research_id).first()
        )

        # Get settings snapshot for thread-safe notification sending
        settings_manager = SettingsManager(db_session)
        settings_snapshot = settings_manager.get_settings_snapshot()

        if research:
            logger.info(
                f"Found research record, creating NotificationManager "
                f"for user {username}"
            )

            # Create notification manager with settings snapshot
            notification_manager = NotificationManager(
                settings_snapshot=settings_snapshot, user_id=username
            )

            # Build full URL for notification
            full_url = build_notification_url(
                f"/research/{research_id}",
                settings_manager=settings_manager,
            )

            # Build notification context with required fields
            context = {
                "query": research.query or "Unknown query",
                "research_id": research_id,
                "summary": "No summary available",
                "url": full_url,
            }

            # Get report content for notification
            from ..storage import get_report_storage

            storage = get_report_storage(session=db_session)
            report_content = storage.get_report(research_id)

            if report_content:
                # Truncate summary if too long
                context["summary"] = (
                    report_content[:200] + "..."
                    if len(report_content) > 200
                    else report_content
                )

            logger.info(
                f"Sending RESEARCH_COMPLETED notification for research "
                f"{research_id} to user {username}"
            )
            logger.debug(f"Notification context: {context}")

            # Send notification using the manager
            result = notification_manager.send_notification(
                event_type=EventType.RESEARCH_COMPLETED,
                context=context,
            )

            if result:
                logger.info(
                    f"Successfully sent completion notification for research {research_id}"
                )
            else:
                logger.warning(
                    f"Completion notification not sent for {research_id} "
                    f"{_format_reason(result)}"
                )

        else:
            logger.warning(
                f"Could not find research {research_id} in database, "
                f"sending notification with minimal details"
            )

            # Create notification manager with settings snapshot
            notification_manager = NotificationManager(
                settings_snapshot=settings_snapshot, user_id=username
            )

            # Build minimal context
            context = {
                "query": f"Research {research_id}",
                "research_id": research_id,
                "summary": "Research completed but details unavailable",
                "url": f"/research/{research_id}",
            }

            minimal_result = notification_manager.send_notification(
                event_type=EventType.RESEARCH_COMPLETED,
                context=context,
            )
            if minimal_result:
                logger.info(
                    f"Sent completion notification for research {research_id} "
                    f"(minimal details)"
                )
            else:
                logger.warning(
                    f"Completion notification not sent for {research_id} "
                    f"(minimal details) {_format_reason(minimal_result)}"
                )

    except RateLimitError:
        logger.warning(
            f"Rate limited sending completion notification for {research_id}"
        )
    except Exception:
        logger.exception(
            f"Failed to send completion notification for {research_id}"
        )


def send_research_failed_notification_from_session(
    username: str,
    research_id: str,
    error_message: str,
    db_session: Session,
) -> None:
    """
    Send research failed notification (research-specific version).

    This is a convenience wrapper for the queue processor that handles
    all notification logic for failed research, including:
    - Research database lookup to get query
    - Context building with sanitized error message
    - All logging and error handling

    Args:
        username: User who owns the research
        research_id: UUID of the research
        error_message: Error message (will be sanitized for security)
        db_session: Database session to fetch research and settings from
    """
    try:
        logger.info(
            f"Starting failed notification process for research {research_id}, "
            f"user {username}"
        )

        # Import here to avoid circular dependencies
        from ..database.models import ResearchHistory
        from ..settings import SettingsManager
        from .manager import NotificationManager

        # Get research details for notification
        research = (
            db_session.query(ResearchHistory).filter_by(id=research_id).first()
        )

        # Get settings snapshot for thread-safe notification sending
        settings_manager = SettingsManager(db_session)
        settings_snapshot = settings_manager.get_settings_snapshot()

        # Sanitize error message for notification to avoid exposing
        # sensitive information (as noted by github-advanced-security)
        safe_error = "Research failed. Check logs for details."

        if research:
            logger.info(
                f"Found research record, creating NotificationManager "
                f"for user {username}"
            )

            # Create notification manager with settings snapshot
            notification_manager = NotificationManager(
                settings_snapshot=settings_snapshot, user_id=username
            )

            # Build notification context
            context = {
                "query": research.query or "Unknown query",
                "research_id": research_id,
                "error": safe_error,
            }

            logger.info(
                f"Sending RESEARCH_FAILED notification for research "
                f"{research_id} to user {username}"
            )
            logger.debug(f"Notification context: {context}")

            # Send notification using the manager
            result = notification_manager.send_notification(
                event_type=EventType.RESEARCH_FAILED,
                context=context,
            )

            if result:
                logger.info(
                    f"Successfully sent failure notification for research {research_id}"
                )
            else:
                logger.warning(
                    f"Failure notification not sent for {research_id} "
                    f"{_format_reason(result)}"
                )

        else:
            logger.warning(
                f"Could not find research {research_id} in database, "
                f"sending notification with minimal details"
            )

            # Create notification manager with settings snapshot
            notification_manager = NotificationManager(
                settings_snapshot=settings_snapshot, user_id=username
            )

            # Build minimal context
            context = {
                "query": f"Research {research_id}",
                "research_id": research_id,
                "error": safe_error,
            }

            minimal_result = notification_manager.send_notification(
                event_type=EventType.RESEARCH_FAILED,
                context=context,
            )
            if minimal_result:
                logger.info(
                    f"Sent failure notification for research {research_id} "
                    f"(minimal details)"
                )
            else:
                logger.warning(
                    f"Failure notification not sent for {research_id} "
                    f"(minimal details) {_format_reason(minimal_result)}"
                )

    except RateLimitError:
        logger.warning(
            f"Rate limited sending failure notification for {research_id}"
        )
    except Exception:
        logger.exception(
            f"Failed to send failure notification for {research_id}"
        )