raxe 0.4.6__py3-none-any.whl

raxe/domain/analytics/statistics.py

@@ -0,0 +1,207 @@
+"""Pure usage statistics functions - no I/O.
+
+This module contains pure functions for calculating usage statistics (DAU, WAU, MAU).
+All functions are stateless and perform no I/O operations.
+
+CRITICAL: This is domain layer - NO database, network, or file operations.
+"""
+from datetime import date, timedelta
+
+from .models import UsageStatistics
+
+
+def calculate_dau(
+    scan_dates_by_user: dict[str, list[date]],
+    target_date: date,
+) -> int:
+    """Calculate Daily Active Users for a specific date.
+
+    Pure function - counts unique users who scanned on target date.
+
+    Args:
+        scan_dates_by_user: Map of user_id -> list of scan dates
+        target_date: Date to calculate DAU for
+
+    Returns:
+        Number of unique users who scanned on target_date
+
+    Example:
+        >>> data = {
+        ...     "user1": [date(2025, 1, 15), date(2025, 1, 16)],
+        ...     "user2": [date(2025, 1, 15)],
+        ...     "user3": [date(2025, 1, 14)],
+        ... }
+        >>> calculate_dau(data, date(2025, 1, 15))
+        2
+    """
+    active_users = {
+        user_id
+        for user_id, dates in scan_dates_by_user.items()
+        if target_date in dates
+    }
+    return len(active_users)
+
+
+def calculate_wau(
+    scan_dates_by_user: dict[str, list[date]],
+    week_end: date,
+) -> int:
+    """Calculate Weekly Active Users for week ending on week_end.
+
+    Pure function - counts unique users who scanned in last 7 days.
+
+    Args:
+        scan_dates_by_user: Map of user_id -> list of scan dates
+        week_end: Last day of the week to calculate WAU for
+
+    Returns:
+        Number of unique users who scanned in the 7-day window
+
+    Example:
+        >>> data = {
+        ...     "user1": [date(2025, 1, 10), date(2025, 1, 15)],
+        ...     "user2": [date(2025, 1, 15)],
+        ...     "user3": [date(2025, 1, 8)],  # Outside window
+        ... }
+        >>> calculate_wau(data, date(2025, 1, 15))
+        2
+    """
+    week_start = week_end - timedelta(days=6)
+    active_users = {
+        user_id
+        for user_id, dates in scan_dates_by_user.items()
+        if any(week_start <= d <= week_end for d in dates)
+    }
+    return len(active_users)
+
+
+def calculate_mau(
+    scan_dates_by_user: dict[str, list[date]],
+    month_end: date,
+) -> int:
+    """Calculate Monthly Active Users for month ending on month_end.
+
+    Pure function - counts unique users who scanned in last 30 days.
+
+    Args:
+        scan_dates_by_user: Map of user_id -> list of scan dates
+        month_end: Last day of the month to calculate MAU for
+
+    Returns:
+        Number of unique users who scanned in the 30-day window
+
+    Example:
+        >>> data = {
+        ...     "user1": [date(2025, 1, 1), date(2025, 1, 31)],
+        ...     "user2": [date(2025, 1, 31)],
+        ...     "user3": [date(2024, 12, 31)],  # Outside window
+        ... }
+        >>> calculate_mau(data, date(2025, 1, 31))
+        2
+    """
+    month_start = month_end - timedelta(days=29)
+    active_users = {
+        user_id
+        for user_id, dates in scan_dates_by_user.items()
+        if any(month_start <= d <= month_end for d in dates)
+    }
+    return len(active_users)
+
+
+def calculate_usage_statistics(
+    scan_dates_by_user: dict[str, list[date]],
+    period_start: date,
+    period_end: date,
+) -> UsageStatistics:
+    """Calculate comprehensive usage statistics for a period.
+
+    Pure function - aggregates all usage metrics.
+
+    Args:
+        scan_dates_by_user: Map of user_id -> list of scan dates
+        period_start: Start of the measurement period
+        period_end: End of the measurement period
+
+    Returns:
+        UsageStatistics with DAU, WAU, MAU, and scan metrics
+
+    Example:
+        >>> data = {
+        ...     "user1": [date(2025, 1, 15), date(2025, 1, 16)],
+        ...     "user2": [date(2025, 1, 15)],
+        ... }
+        >>> stats = calculate_usage_statistics(data, date(2025, 1, 1), date(2025, 1, 16))
+        >>> stats.total_scans
+        3
+        >>> stats.dau
+        1
+    """
+    # Filter scans within period
+    period_scans = {
+        user_id: [d for d in dates if period_start <= d <= period_end]
+        for user_id, dates in scan_dates_by_user.items()
+    }
+
+    total_scans = sum(len(dates) for dates in period_scans.values())
+    active_users = len([dates for dates in period_scans.values() if dates])
+
+    return UsageStatistics(
+        period_start=period_start,
+        period_end=period_end,
+        dau=calculate_dau(scan_dates_by_user, period_end),
+        wau=calculate_wau(scan_dates_by_user, period_end),
+        mau=calculate_mau(scan_dates_by_user, period_end),
+        total_scans=total_scans,
+        avg_scans_per_user=total_scans / active_users if active_users > 0 else 0.0,
+    )
+
+
+def calculate_stickiness(dau: int, mau: int) -> float:
+    """Calculate stickiness ratio (DAU/MAU).
+
+    Pure function - calculates engagement ratio.
+
+    Stickiness measures how many of your monthly users are active daily.
+    Higher is better (max 100% if DAU == MAU).
+
+    Args:
+        dau: Daily Active Users
+        mau: Monthly Active Users
+
+    Returns:
+        Stickiness ratio as percentage (0.0 to 100.0)
+
+    Example:
+        >>> calculate_stickiness(dau=50, mau=200)
+        25.0
+    """
+    if mau == 0:
+        return 0.0
+    return (dau / mau) * 100.0
+
+
+def calculate_growth_rate(
+    current_mau: int,
+    previous_mau: int,
+) -> float:
+    """Calculate month-over-month growth rate.
+
+    Pure function - calculates percentage change.
+
+    Args:
+        current_mau: Current month's MAU
+        previous_mau: Previous month's MAU
+
+    Returns:
+        Growth rate as percentage (can be negative)
+
+    Example:
+        >>> calculate_growth_rate(current_mau=120, previous_mau=100)
+        20.0
+        >>> calculate_growth_rate(current_mau=80, previous_mau=100)
+        -20.0
+    """
+    if previous_mau == 0:
+        return 0.0 if current_mau == 0 else 100.0
+
+    return ((current_mau - previous_mau) / previous_mau) * 100.0

raxe/domain/analytics/streaks.py

@@ -0,0 +1,173 @@
+"""Pure streak calculation functions - no I/O.
+
+This module contains pure functions for calculating user engagement streaks.
+All functions are stateless and perform no I/O operations.
+
+CRITICAL: This is domain layer - NO database, network, or file operations.
+"""
+from datetime import date, timedelta
+
+from .models import StreakMetrics
+
+
+def calculate_streaks(
+    installation_id: str,
+    scan_dates: list[date],
+    *,
+    reference_date: date | None = None,
+) -> StreakMetrics:
+    """Calculate streak metrics for a user.
+
+    Pure function - takes sorted scan dates, returns streak metrics.
+
+    A "streak" is consecutive days with at least one scan. Current streak
+    only counts if the last scan was today or yesterday.
+
+    Args:
+        installation_id: Unique user identifier
+        scan_dates: List of dates user performed scans (will be sorted/deduped)
+        reference_date: Date to use as "today" (defaults to date.today(), for testing)
+
+    Returns:
+        StreakMetrics with current and longest streaks
+
+    Example:
+        >>> metrics = calculate_streaks(
+        ...     installation_id="abc123",
+        ...     scan_dates=[
+        ...         date(2025, 1, 1),
+        ...         date(2025, 1, 2),
+        ...         date(2025, 1, 3),
+        ...         date(2025, 1, 5),  # Gap here
+        ...         date(2025, 1, 6),
+        ...     ],
+        ...     reference_date=date(2025, 1, 6)
+        ... )
+        >>> metrics.longest_streak
+        3
+        >>> metrics.current_streak
+        2
+    """
+    if reference_date is None:
+        reference_date = date.today()
+
+    if not scan_dates:
+        return StreakMetrics(
+            installation_id=installation_id,
+            current_streak=0,
+            longest_streak=0,
+            total_scan_days=0,
+            last_scan_date=reference_date,
+        )
+
+    # Sort and deduplicate scan dates
+    unique_dates = sorted(set(scan_dates))
+
+    # Calculate current streak (from reference_date backwards)
+    current_streak = _calculate_current_streak(unique_dates, reference_date)
+
+    # Calculate longest streak (historical)
+    longest_streak = _calculate_longest_streak(unique_dates)
+
+    # Longest streak is at least as long as current streak
+    longest_streak = max(longest_streak, current_streak)
+
+    return StreakMetrics(
+        installation_id=installation_id,
+        current_streak=current_streak,
+        longest_streak=longest_streak,
+        total_scan_days=len(unique_dates),
+        last_scan_date=unique_dates[-1],
+    )
+
+
+def _calculate_current_streak(unique_dates: list[date], reference_date: date) -> int:
+    """Calculate current streak from reference_date backwards.
+
+    A current streak only counts if the last scan was today or yesterday
+    relative to reference_date.
+
+    Args:
+        unique_dates: Sorted list of unique scan dates
+        reference_date: Date to use as "today"
+
+    Returns:
+        Current consecutive day streak (0 if broken)
+    """
+    yesterday = reference_date - timedelta(days=1)
+
+    # Current streak only exists if last scan was today or yesterday
+    if unique_dates[-1] not in (reference_date, yesterday):
+        return 0
+
+    current_streak = 1
+
+    # Walk backwards counting consecutive days
+    for i in range(len(unique_dates) - 2, -1, -1):
+        expected_prev_date = unique_dates[i + 1] - timedelta(days=1)
+        if unique_dates[i] == expected_prev_date:
+            current_streak += 1
+        else:
+            break
+
+    return current_streak
+
+
+def _calculate_longest_streak(unique_dates: list[date]) -> int:
+    """Calculate longest historical streak.
+
+    Args:
+        unique_dates: Sorted list of unique scan dates
+
+    Returns:
+        Longest consecutive day streak ever achieved
+    """
+    if not unique_dates:
+        return 0
+
+    longest_streak = 1
+    current_run = 1
+
+    for i in range(1, len(unique_dates)):
+        days_diff = (unique_dates[i] - unique_dates[i - 1]).days
+
+        if days_diff == 1:
+            # Consecutive day - extend current run
+            current_run += 1
+            longest_streak = max(longest_streak, current_run)
+        else:
+            # Gap - reset current run
+            current_run = 1
+
+    return longest_streak
+
+
+def compare_streaks(
+    current: StreakMetrics,
+    previous: StreakMetrics,
+) -> dict[str, int]:
+    """Compare two streak metrics to show change.
+
+    Pure function - calculates deltas between metrics.
+
+    Args:
+        current: Current streak metrics
+        previous: Previous streak metrics
+
+    Returns:
+        Dictionary with delta values for each metric
+
+    Example:
+        >>> current = StreakMetrics("u1", 5, 10, 100, date(2025, 1, 6))
+        >>> previous = StreakMetrics("u1", 3, 8, 95, date(2025, 1, 5))
+        >>> deltas = compare_streaks(current, previous)
+        >>> deltas["current_streak"]
+        2
+        >>> deltas["longest_streak"]
+        2
+    """
+    return {
+        "current_streak": current.current_streak - previous.current_streak,
+        "longest_streak": current.longest_streak - previous.longest_streak,
+        "total_scan_days": current.total_scan_days - previous.total_scan_days,
+    }

raxe/domain/engine/__init__.py

@@ -0,0 +1,15 @@
+"""Rule execution engine.
+
+Pure domain layer - executes rules to detect threats.
+All components are stateless with no I/O operations.
+"""
+from raxe.domain.engine.executor import Detection, RuleExecutor, ScanResult
+from raxe.domain.engine.matcher import Match, PatternMatcher
+
+__all__ = [
+    "Detection",
+    "Match",
+    "PatternMatcher",
+    "RuleExecutor",
+    "ScanResult",
+]