raxe 0.4.6__py3-none-any.whl

raxe/domain/analytics/__init__.py

@@ -0,0 +1,97 @@
+"""Pure analytics domain layer - no I/O operations.
+
+This package contains all business logic for analytics calculations.
+All functions are pure - they take data and return data without side effects.
+
+CRITICAL: This is domain layer - NO database, network, or file operations allowed.
+
+Public API:
+    Models:
+        - RetentionMetrics
+        - StreakMetrics
+        - UsageStatistics
+        - Achievement
+        - UserAchievements
+
+    Functions:
+        - calculate_retention()
+        - calculate_cohort_retention()
+        - calculate_streaks()
+        - calculate_dau()
+        - calculate_wau()
+        - calculate_mau()
+        - calculate_usage_statistics()
+        - calculate_user_achievements()
+        - ACHIEVEMENTS (const list)
+"""
+
+# Models
+# Achievement functions
+from .achievements import (
+    ACHIEVEMENTS,
+    calculate_user_achievements,
+    check_achievement_unlocked,
+    find_next_achievements,
+    get_achievement_by_id,
+    get_leaderboard_points,
+)
+from .models import (
+    Achievement,
+    RetentionMetrics,
+    StreakMetrics,
+    UsageStatistics,
+    UserAchievements,
+)
+
+# Retention functions
+from .retention import (
+    calculate_cohort_retention,
+    calculate_retention,
+    calculate_retention_rate,
+)
+
+# Statistics functions
+from .statistics import (
+    calculate_dau,
+    calculate_growth_rate,
+    calculate_mau,
+    calculate_stickiness,
+    calculate_usage_statistics,
+    calculate_wau,
+)
+
+# Streak functions
+from .streaks import (
+    calculate_streaks,
+    compare_streaks,
+)
+
+__all__ = [
+    # Achievements
+    "ACHIEVEMENTS",
+    "Achievement",
+    # Models
+    "RetentionMetrics",
+    "StreakMetrics",
+    "UsageStatistics",
+    "UserAchievements",
+    "calculate_cohort_retention",
+    # Statistics
+    "calculate_dau",
+    "calculate_growth_rate",
+    "calculate_mau",
+    # Retention
+    "calculate_retention",
+    "calculate_retention_rate",
+    "calculate_stickiness",
+    # Streaks
+    "calculate_streaks",
+    "calculate_usage_statistics",
+    "calculate_user_achievements",
+    "calculate_wau",
+    "check_achievement_unlocked",
+    "compare_streaks",
+    "find_next_achievements",
+    "get_achievement_by_id",
+    "get_leaderboard_points",
+]

raxe/domain/analytics/achievements.py

@@ -0,0 +1,306 @@
+"""Pure achievement calculation functions - no I/O.
+
+This module contains pure functions for calculating user achievements.
+All functions are stateless and perform no I/O operations.
+
+CRITICAL: This is domain layer - NO database, network, or file operations.
+"""
+
+from .models import Achievement, StreakMetrics, UserAchievements
+
+# Define all achievements (const data, not I/O)
+ACHIEVEMENTS: list[Achievement] = [
+    Achievement(
+        id="first_scan",
+        name="First Scan",
+        description="Completed your first scan",
+        points=10,
+        unlock_condition="scan_count >= 1"
+    ),
+    Achievement(
+        id="getting_started",
+        name="Getting Started",
+        description="Completed 10 scans",
+        points=25,
+        unlock_condition="scan_count >= 10"
+    ),
+    Achievement(
+        id="power_user",
+        name="Power User",
+        description="Completed 100 scans",
+        points=100,
+        unlock_condition="scan_count >= 100"
+    ),
+    Achievement(
+        id="super_user",
+        name="Super User",
+        description="Completed 1,000 scans",
+        points=500,
+        unlock_condition="scan_count >= 1000"
+    ),
+    Achievement(
+        id="mega_user",
+        name="Mega User",
+        description="Completed 10,000 scans",
+        points=2000,
+        unlock_condition="scan_count >= 10000"
+    ),
+    Achievement(
+        id="streak_3",
+        name="Three Day Streak",
+        description="3-day scan streak",
+        points=20,
+        unlock_condition="streak_count >= 3"
+    ),
+    Achievement(
+        id="streak_7",
+        name="Week Warrior",
+        description="7-day scan streak",
+        points=50,
+        unlock_condition="streak_count >= 7"
+    ),
+    Achievement(
+        id="streak_30",
+        name="Monthly Master",
+        description="30-day scan streak",
+        points=200,
+        unlock_condition="streak_count >= 30"
+    ),
+    Achievement(
+        id="streak_100",
+        name="Century Streak",
+        description="100-day scan streak",
+        points=1000,
+        unlock_condition="streak_count >= 100"
+    ),
+    Achievement(
+        id="streak_365",
+        name="Year Legend",
+        description="365-day scan streak",
+        points=5000,
+        unlock_condition="streak_count >= 365"
+    ),
+]
+
+
+def get_achievement_by_id(achievement_id: str) -> Achievement | None:
+    """Get achievement definition by ID.
+
+    Pure function - looks up achievement in const data.
+
+    Args:
+        achievement_id: Unique achievement identifier
+
+    Returns:
+        Achievement object, or None if not found
+
+    Example:
+        >>> ach = get_achievement_by_id("first_scan")
+        >>> ach.name
+        'First Scan'
+    """
+    for achievement in ACHIEVEMENTS:
+        if achievement.id == achievement_id:
+            return achievement
+    return None
+
+
+def check_achievement_unlocked(
+    achievement: Achievement,
+    *,
+    scan_count: int,
+    streak_count: int,
+) -> bool:
+    """Check if achievement is unlocked based on user stats.
+
+    Pure function - evaluates unlock conditions.
+
+    Currently supports two condition types:
+    - "scan_count >= N": User has N or more scans
+    - "streak_count >= N": User has N or more day streak
+
+    Args:
+        achievement: Achievement to check
+        scan_count: User's total scan count
+        streak_count: User's longest streak count
+
+    Returns:
+        True if achievement is unlocked, False otherwise
+
+    Example:
+        >>> ach = Achievement("test", "Test", "Test", 10, "scan_count >= 5")
+        >>> check_achievement_unlocked(ach, scan_count=10, streak_count=0)
+        True
+        >>> check_achievement_unlocked(ach, scan_count=3, streak_count=0)
+        False
+    """
+    condition = achievement.unlock_condition
+
+    # Parse condition and evaluate
+    if "scan_count >=" in condition:
+        threshold = int(condition.split(">=")[1].strip())
+        return scan_count >= threshold
+    elif "streak_count >=" in condition:
+        threshold = int(condition.split(">=")[1].strip())
+        return streak_count >= threshold
+
+    # Unknown condition type - default to False
+    return False
+
+
+def calculate_user_achievements(
+    installation_id: str,
+    scan_count: int,
+    streak_metrics: StreakMetrics,
+) -> UserAchievements:
+    """Calculate which achievements a user has unlocked.
+
+    Pure function - evaluates all achievements against user stats.
+
+    Args:
+        installation_id: Unique user identifier
+        scan_count: Total scans performed by user
+        streak_metrics: User's streak metrics
+
+    Returns:
+        UserAchievements with unlocked achievements and total points
+
+    Example:
+        >>> from datetime import date
+        >>> streaks = StreakMetrics("u1", 7, 7, 10, date(2025, 1, 15))
+        >>> achievements = calculate_user_achievements("u1", 100, streaks)
+        >>> "power_user" in achievements.unlocked_achievements
+        True
+        >>> "streak_7" in achievements.unlocked_achievements
+        True
+        >>> achievements.total_points > 0
+        True
+    """
+    unlocked = [
+        achievement.id
+        for achievement in ACHIEVEMENTS
+        if check_achievement_unlocked(
+            achievement,
+            scan_count=scan_count,
+            streak_count=streak_metrics.longest_streak,
+        )
+    ]
+
+    total_points = sum(
+        ach.points
+        for ach in ACHIEVEMENTS
+        if ach.id in unlocked
+    )
+
+    return UserAchievements(
+        installation_id=installation_id,
+        unlocked_achievements=unlocked,
+        total_points=total_points,
+        scan_count=scan_count,
+        streak_count=streak_metrics.longest_streak,
+    )
+
+
+def find_next_achievements(
+    current_achievements: UserAchievements,
+    *,
+    max_results: int = 3,
+) -> list[tuple[Achievement, int]]:
+    """Find next achievements user can unlock.
+
+    Pure function - identifies closest locked achievements.
+
+    Args:
+        current_achievements: User's current achievement state
+        max_results: Maximum number of next achievements to return
+
+    Returns:
+        List of (achievement, progress_needed) tuples, sorted by closest first
+
+    Example:
+        >>> achievements = UserAchievements("u1", ["first_scan"], 10, 5, 2)
+        >>> next_achs = find_next_achievements(achievements, max_results=2)
+        >>> len(next_achs) <= 2
+        True
+    """
+    unlocked_set = set(current_achievements.unlocked_achievements)
+    locked_achievements = [
+        ach for ach in ACHIEVEMENTS
+        if ach.id not in unlocked_set
+    ]
+
+    # Calculate progress needed for each locked achievement
+    achievements_with_progress = []
+    for ach in locked_achievements:
+        progress_needed = _calculate_progress_needed(
+            ach,
+            scan_count=current_achievements.scan_count,
+            streak_count=current_achievements.streak_count,
+        )
+        achievements_with_progress.append((ach, progress_needed))
+
+    # Sort by progress needed (closest first)
+    achievements_with_progress.sort(key=lambda x: x[1])
+
+    return achievements_with_progress[:max_results]
+
+
+def _calculate_progress_needed(
+    achievement: Achievement,
+    *,
+    scan_count: int,
+    streak_count: int,
+) -> int:
+    """Calculate how much progress is needed to unlock achievement.
+
+    Args:
+        achievement: Achievement to check
+        scan_count: User's current scan count
+        streak_count: User's current streak count
+
+    Returns:
+        Number of scans/days needed (0 if already unlocked)
+    """
+    condition = achievement.unlock_condition
+
+    if "scan_count >=" in condition:
+        threshold = int(condition.split(">=")[1].strip())
+        return max(0, threshold - scan_count)
+    elif "streak_count >=" in condition:
+        threshold = int(condition.split(">=")[1].strip())
+        return max(0, threshold - streak_count)
+
+    return 0
+
+
+def get_leaderboard_points(
+    user_achievements: dict[str, UserAchievements]
+) -> list[tuple[str, int]]:
+    """Generate leaderboard sorted by total points.
+
+    Pure function - aggregates and sorts achievement data.
+
+    Args:
+        user_achievements: Map of installation_id -> UserAchievements
+
+    Returns:
+        List of (installation_id, total_points) tuples, sorted descending
+
+    Example:
+        >>> achievements = {
+        ...     "user1": UserAchievements("user1", [], 100, 0, 0),
+        ...     "user2": UserAchievements("user2", [], 200, 0, 0),
+        ... }
+        >>> leaderboard = get_leaderboard_points(achievements)
+        >>> leaderboard[0][0]
+        'user2'
+    """
+    leaderboard = [
+        (installation_id, achievements.total_points)
+        for installation_id, achievements in user_achievements.items()
+    ]
+
+    # Sort by points descending
+    leaderboard.sort(key=lambda x: x[1], reverse=True)
+
+    return leaderboard

raxe/domain/analytics/models.py

@@ -0,0 +1,120 @@
+"""Pure analytics domain models - no I/O.
+
+This module contains immutable value objects for analytics.
+All models are frozen dataclasses to ensure immutability.
+
+CRITICAL: This is domain layer - NO I/O operations allowed.
+"""
+from dataclasses import dataclass, field
+from datetime import date
+
+
+@dataclass(frozen=True)
+class RetentionMetrics:
+    """Immutable retention metrics for a user.
+
+    Tracks user retention across different time windows:
+    - Day 1: Did user scan within 24 hours of install?
+    - Day 7: Did user scan between day 6-8?
+    - Day 30: Did user scan between day 29-31?
+
+    Args:
+        installation_id: Unique identifier for this installation
+        install_date: Date when user installed RAXE
+        day1_retained: True if user scanned on day 1
+        day7_retained: True if user scanned around day 7
+        day30_retained: True if user scanned around day 30
+        total_scans: Total number of scans performed
+        last_scan_date: Most recent scan date, if any
+    """
+    installation_id: str
+    install_date: date
+    day1_retained: bool
+    day7_retained: bool
+    day30_retained: bool
+    total_scans: int
+    last_scan_date: date | None = None
+
+
+@dataclass(frozen=True)
+class StreakMetrics:
+    """Immutable streak metrics for a user.
+
+    Tracks user engagement streaks (consecutive days with scans).
+
+    Args:
+        installation_id: Unique identifier for this installation
+        current_streak: Current consecutive day streak (0 if broken)
+        longest_streak: Longest consecutive day streak ever achieved
+        total_scan_days: Total unique days with at least one scan
+        last_scan_date: Most recent scan date
+    """
+    installation_id: str
+    current_streak: int
+    longest_streak: int
+    total_scan_days: int
+    last_scan_date: date
+
+
+@dataclass(frozen=True)
+class UsageStatistics:
+    """Immutable usage statistics for a time period.
+
+    Aggregated metrics for understanding user engagement.
+
+    Args:
+        period_start: Start of the measurement period
+        period_end: End of the measurement period
+        dau: Daily Active Users (users who scanned on period_end)
+        wau: Weekly Active Users (users who scanned in last 7 days)
+        mau: Monthly Active Users (users who scanned in last 30 days)
+        total_scans: Total scans performed in period
+        avg_scans_per_user: Average scans per active user
+    """
+    period_start: date
+    period_end: date
+    dau: int
+    wau: int
+    mau: int
+    total_scans: int
+    avg_scans_per_user: float
+
+
+@dataclass(frozen=True)
+class Achievement:
+    """Immutable achievement definition.
+
+    Represents a gamification achievement users can unlock.
+
+    Args:
+        id: Unique achievement identifier (e.g., "first_scan")
+        name: Display name (e.g., "First Scan")
+        description: User-facing description
+        points: Points awarded for unlocking
+        unlock_condition: Machine-readable condition (e.g., "scan_count >= 100")
+    """
+    id: str
+    name: str
+    description: str
+    points: int
+    unlock_condition: str
+
+
+@dataclass(frozen=True)
+class UserAchievements:
+    """Immutable user achievement progress.
+
+    Tracks which achievements a user has unlocked and their total points.
+
+    Args:
+        installation_id: Unique identifier for this installation
+        unlocked_achievements: List of achievement IDs the user has unlocked
+        total_points: Sum of points from all unlocked achievements
+        scan_count: Total scans (cached for achievement checking)
+        streak_count: Longest streak (cached for achievement checking)
+    """
+    installation_id: str
+    unlocked_achievements: list[str] = field(default_factory=list)
+    total_points: int = 0
+    scan_count: int = 0
+    streak_count: int = 0

raxe/domain/analytics/retention.py

@@ -0,0 +1,168 @@
+"""Pure retention calculation functions - no I/O.
+
+This module contains pure functions for calculating user retention metrics.
+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 RetentionMetrics
+
+
+def calculate_retention(
+    installation_id: str,
+    install_date: date,
+    scan_dates: list[date],
+) -> RetentionMetrics:
+    """Calculate retention metrics for a single user.
+
+    Pure function - takes data, returns data, no I/O.
+
+    Retention windows:
+    - Day 1: Scan occurred on install_date + 1 day
+    - Day 7: Scan occurred on days 6, 7, or 8 after install
+    - Day 30: Scan occurred on days 29, 30, or 31 after install
+
+    Args:
+        installation_id: Unique user identifier
+        install_date: When user installed RAXE
+        scan_dates: List of dates user performed scans (may contain duplicates)
+
+    Returns:
+        RetentionMetrics with day 1/7/30 retention calculated
+
+    Example:
+        >>> metrics = calculate_retention(
+        ...     installation_id="abc123",
+        ...     install_date=date(2025, 1, 1),
+        ...     scan_dates=[date(2025, 1, 2), date(2025, 1, 8), date(2025, 1, 31)]
+        ... )
+        >>> metrics.day1_retained
+        True
+        >>> metrics.day7_retained
+        True
+        >>> metrics.day30_retained
+        True
+    """
+    if not scan_dates:
+        return RetentionMetrics(
+            installation_id=installation_id,
+            install_date=install_date,
+            day1_retained=False,
+            day7_retained=False,
+            day30_retained=False,
+            total_scans=0,
+            last_scan_date=None,
+        )
+
+    # Convert to set for O(1) lookup
+    scan_date_set = set(scan_dates)
+
+    # Day 1 retention: scan on the day after install
+    day1_date = install_date + timedelta(days=1)
+    day1_retained = day1_date in scan_date_set
+
+    # Day 7 retention: scan between day 6-8 (inclusive)
+    day7_retained = any(
+        (install_date + timedelta(days=d)) in scan_date_set
+        for d in range(6, 9)
+    )
+
+    # Day 30 retention: scan between day 29-31 (inclusive)
+    day30_retained = any(
+        (install_date + timedelta(days=d)) in scan_date_set
+        for d in range(29, 32)
+    )
+
+    return RetentionMetrics(
+        installation_id=installation_id,
+        install_date=install_date,
+        day1_retained=day1_retained,
+        day7_retained=day7_retained,
+        day30_retained=day30_retained,
+        total_scans=len(scan_dates),
+        last_scan_date=max(scan_dates) if scan_dates else None,
+    )
+
+
+def calculate_cohort_retention(
+    cohort: dict[str, tuple[date, list[date]]]
+) -> dict[str, RetentionMetrics]:
+    """Calculate retention for an entire cohort of users.
+
+    Pure function - processes multiple users in batch.
+
+    Args:
+        cohort: Map of installation_id -> (install_date, scan_dates)
+
+    Returns:
+        Map of installation_id -> RetentionMetrics
+
+    Example:
+        >>> cohort = {
+        ...     "user1": (date(2025, 1, 1), [date(2025, 1, 2)]),
+        ...     "user2": (date(2025, 1, 1), [date(2025, 1, 8)]),
+        ... }
+        >>> results = calculate_cohort_retention(cohort)
+        >>> results["user1"].day1_retained
+        True
+        >>> results["user2"].day7_retained
+        True
+    """
+    return {
+        installation_id: calculate_retention(
+            installation_id=installation_id,
+            install_date=install_date,
+            scan_dates=scan_dates,
+        )
+        for installation_id, (install_date, scan_dates) in cohort.items()
+    }
+
+
+def calculate_retention_rate(
+    retention_metrics: list[RetentionMetrics],
+    window: str,
+) -> float:
+    """Calculate retention rate for a cohort.
+
+    Pure function - aggregates retention metrics.
+
+    Args:
+        retention_metrics: List of RetentionMetrics for cohort members
+        window: Which retention window to calculate ("day1", "day7", or "day30")
+
+    Returns:
+        Retention rate as a percentage (0.0 to 100.0)
+
+    Raises:
+        ValueError: If window is not one of "day1", "day7", "day30"
+
+    Example:
+        >>> metrics = [
+        ...     RetentionMetrics("u1", date(2025, 1, 1), True, True, False, 10, None),
+        ...     RetentionMetrics("u2", date(2025, 1, 1), True, False, False, 5, None),
+        ...     RetentionMetrics("u3", date(2025, 1, 1), False, False, False, 1, None),
+        ... ]
+        >>> calculate_retention_rate(metrics, "day1")
+        66.66666666666666
+    """
+    if not retention_metrics:
+        return 0.0
+
+    if window not in ("day1", "day7", "day30"):
+        raise ValueError(f"Invalid window: {window}. Must be 'day1', 'day7', or 'day30'")
+
+    # Map window to attribute
+    attr_map = {
+        "day1": "day1_retained",
+        "day7": "day7_retained",
+        "day30": "day30_retained",
+    }
+
+    retained_count = sum(
+        1 for m in retention_metrics
+        if getattr(m, attr_map[window])
+    )
+
+    return (retained_count / len(retention_metrics)) * 100.0