raxe 0.4.6__py3-none-any.whl

raxe/__init__.py

@@ -0,0 +1,101 @@
+"""RAXE - AI Security for LLMs
+
+Privacy-first threat detection for LLM applications.
+
+RAXE provides developer-friendly, privacy-first AI security with:
+- Local-first scanning (PII never leaves your machine)
+- <10ms scan latency (P95)
+- Community-driven threat detection
+- Drop-in LLM client wrappers
+
+Quick Start:
+    >>> from raxe import Raxe
+    >>> raxe = Raxe()
+    >>> result = raxe.scan("Ignore all previous instructions")
+    >>> if result.has_threats:
+    ...     print(f"Threat: {result.severity}")
+
+Decorator Pattern:
+    >>> @raxe.protect
+    ... def generate(prompt: str) -> str:
+    ...     return llm.generate(prompt)
+
+Wrapper Pattern:
+    >>> from openai import OpenAI
+    >>> client = raxe.wrap(OpenAI())
+    >>> # All calls automatically scanned
+
+Architecture:
+    This package follows Clean Architecture:
+    - domain/: Pure business logic (NO I/O)
+    - application/: Use cases and orchestration
+    - infrastructure/: I/O implementations (DB, API, packs)
+    - sdk/: Python SDK (this is the entry point)
+    - cli/: Command-line interface
+
+For more information: https://docs.raxe.ai
+"""
+
+__version__ = "0.4.6"
+__author__ = "RAXE Team"
+__license__ = "Proprietary"
+
+# Core client (PRIMARY EXPORT)
+# Common types
+from raxe.domain.engine.executor import Detection, ScanResult
+from raxe.domain.rules.models import Severity
+from raxe.sdk.client import Raxe
+
+# Exceptions
+from raxe.sdk.exceptions import (
+    RaxeBlockedError,
+    RaxeException,
+    SecurityException,
+)
+
+__all__ = [
+    "Detection",
+    # Core
+    "Raxe",
+    "RaxeBlockedError",
+    # Exceptions
+    "RaxeException",
+    # Types
+    "ScanResult",
+    "SecurityException",
+    "Severity",
+    # Metadata
+    "__version__",
+]
+
+# CLI entry point and Async SDK (always available)
+from raxe.async_sdk import AsyncRaxe  # noqa: F401 - Exported via __all__.append
+from raxe.cli.main import cli  # noqa: F401 - Used by setuptools entry point
+
+__all__.append("AsyncRaxe")
+
+# Wrappers (optional, require respective LLM packages)
+try:
+    from raxe.sdk.wrappers.openai import RaxeOpenAI  # noqa: F401 - Conditionally exported
+
+    __all__.append("RaxeOpenAI")
+except ImportError:
+    # OpenAI not installed, skip wrapper
+    pass
+
+try:
+    from raxe.sdk.wrappers.anthropic import RaxeAnthropic  # noqa: F401 - Conditionally exported
+
+    __all__.append("RaxeAnthropic")
+except ImportError:
+    # Anthropic not installed, skip wrapper
+    pass
+
+__all__.append("cli")
+
+# Telemetry (optional, for advanced users)
+from raxe.application.telemetry_orchestrator import (  # noqa: E402
+    get_orchestrator as get_telemetry,  # noqa: F401
+)
+
+__all__.append("get_telemetry")

raxe/application/__init__.py

@@ -0,0 +1,48 @@
+"""
+Application Layer - Use Cases & Orchestration
+
+This layer coordinates between domain logic and infrastructure.
+It defines the use cases and workflows of the RAXE system.
+
+Responsibilities:
+    - Orchestrate domain + infrastructure
+    - Define use cases (scan prompt, batch scan, etc.)
+    - Handle application-level errors
+    - Coordinate telemetry and upgrades
+    - Manage performance strategies
+
+Pattern:
+    def use_case(domain_service, repository, ...):
+        # 1. Load data via infrastructure
+        data = repository.load()
+
+        # 2. Execute domain logic (pure)
+        result = domain_service.process(data)
+
+        # 3. Save via infrastructure
+        repository.save(result)
+
+        return result
+
+Modules:
+    - scan_pipeline.py: Main scanning pipeline
+    - session_tracker.py: Session lifecycle and activation tracking
+    - telemetry_orchestrator.py: Main telemetry coordination
+    - telemetry_manager.py: Legacy telemetry management
+"""
+
+from .session_tracker import SessionTracker
+from .telemetry_orchestrator import (
+    TelemetryOrchestrator,
+    get_orchestrator,
+    reset_orchestrator,
+)
+
+__all__ = [
+    # Session tracking
+    "SessionTracker",
+    # Telemetry orchestration
+    "TelemetryOrchestrator",
+    "get_orchestrator",
+    "reset_orchestrator",
+]

raxe/application/ab_testing.py

@@ -0,0 +1,170 @@
+"""A/B Testing framework for detector configuration.
+
+Allows gradual rollout and comparison of L1-only vs L1+L2 detection modes.
+"""
+import hashlib
+import logging
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class DetectorMode(Enum):
+    """Detection modes for A/B testing."""
+
+    L1_ONLY = "l1_only"
+    L1_AND_L2 = "l1_and_l2"
+
+
+@dataclass(frozen=True)
+class ABTestConfig:
+    """A/B test configuration."""
+
+    l2_rollout_percentage: float = 10.0  # Default 10% rollout
+    enabled: bool = True
+    customer_overrides: dict[str, DetectorMode] = None
+
+    def __post_init__(self):
+        """Validate configuration."""
+        if not 0 <= self.l2_rollout_percentage <= 100:
+            raise ValueError("Rollout percentage must be between 0 and 100")
+
+        # Handle frozen dataclass field initialization
+        if self.customer_overrides is None:
+            object.__setattr__(self, 'customer_overrides', {})
+
+
+class ABTestManager:
+    """Manages A/B testing for detector modes."""
+
+    def __init__(self, config: ABTestConfig = None):
+        """Initialize with config.
+
+        Args:
+            config: AB test configuration
+        """
+        self.config = config or ABTestConfig()
+        self._cohort_cache = {}
+        logger.info(
+            f"AB test manager initialized: L2 rollout={self.config.l2_rollout_percentage}%"
+        )
+
+    def get_detector_mode(
+        self,
+        customer_id: str | None = None,
+        session_id: str | None = None
+    ) -> DetectorMode:
+        """Determine which detector mode to use.
+
+        Uses consistent hashing to assign users to cohorts.
+
+        Args:
+            customer_id: Customer identifier for consistent assignment
+            session_id: Session identifier as fallback
+
+        Returns:
+            DetectorMode to use for this request
+        """
+        if not self.config.enabled:
+            return DetectorMode.L1_AND_L2  # Default to full detection
+
+        # Check for customer override
+        if customer_id and customer_id in self.config.customer_overrides:
+            mode = self.config.customer_overrides[customer_id]
+            logger.debug(f"Customer {customer_id} has override: {mode.value}")
+            return mode
+
+        # Use customer_id or session_id for consistent assignment
+        cohort_key = customer_id or session_id or "anonymous"
+
+        # Check cache
+        if cohort_key in self._cohort_cache:
+            return self._cohort_cache[cohort_key]
+
+        # Calculate cohort assignment using consistent hashing
+        mode = self._calculate_cohort(cohort_key)
+
+        # Cache the assignment
+        self._cohort_cache[cohort_key] = mode
+
+        logger.debug(f"Assigned {cohort_key} to mode: {mode.value}")
+        return mode
+
+    def _calculate_cohort(self, cohort_key: str) -> DetectorMode:
+        """Calculate cohort assignment using consistent hashing.
+
+        Args:
+            cohort_key: Key to hash for assignment
+
+        Returns:
+            Assigned detector mode
+        """
+        # Hash the key to get consistent assignment
+        hash_value = hashlib.sha256(cohort_key.encode()).hexdigest()
+
+        # Convert first 8 hex chars to int (32-bit value)
+        hash_int = int(hash_value[:8], 16)
+
+        # Map to 0-100 range
+        percentage = (hash_int % 10000) / 100.0
+
+        # Assign based on rollout percentage
+        if percentage < self.config.l2_rollout_percentage:
+            return DetectorMode.L1_AND_L2
+        else:
+            return DetectorMode.L1_ONLY
+
+    def record_outcome(
+        self,
+        mode: DetectorMode,
+        customer_id: str | None,
+        detected_threat: bool,
+        processing_time_ms: float
+    ) -> None:
+        """Record A/B test outcome for analysis.
+
+        Args:
+            mode: Which mode was used
+            customer_id: Customer identifier
+            detected_threat: Whether a threat was detected
+            processing_time_ms: Processing time in milliseconds
+        """
+        # In production, this would send to analytics
+        logger.info(
+            f"AB test outcome: mode={mode.value}, "
+            f"customer={customer_id or 'anonymous'}, "
+            f"threat={detected_threat}, "
+            f"time_ms={processing_time_ms:.2f}"
+        )
+
+    def get_cohort_stats(self) -> dict:
+        """Get current cohort statistics.
+
+        Returns:
+            Statistics about cohort assignments
+        """
+        l1_only_count = sum(
+            1 for mode in self._cohort_cache.values()
+            if mode == DetectorMode.L1_ONLY
+        )
+        l1_l2_count = sum(
+            1 for mode in self._cohort_cache.values()
+            if mode == DetectorMode.L1_AND_L2
+        )
+
+        total = len(self._cohort_cache)
+
+        return {
+            "total_assignments": total,
+            "l1_only": l1_only_count,
+            "l1_and_l2": l1_l2_count,
+            "l1_only_percentage": (l1_only_count / total * 100) if total > 0 else 0,
+            "l1_and_l2_percentage": (l1_l2_count / total * 100) if total > 0 else 0,
+            "config_rollout_percentage": self.config.l2_rollout_percentage,
+        }
+
+    def clear_cache(self) -> None:
+        """Clear cohort assignment cache."""
+        self._cohort_cache.clear()
+        logger.debug("Cohort cache cleared")

raxe/application/analytics/__init__.py

@@ -0,0 +1,30 @@
+"""Application layer for analytics services.
+
+This package contains orchestration services that coordinate
+between pure domain logic (calculations) and infrastructure (I/O).
+
+Services:
+    - RetentionService: User retention calculations
+    - StreakService: Activity streak tracking
+    - StatisticsService: DAU/WAU/MAU and usage stats
+    - AchievementService: Achievement evaluation and tracking
+
+All services delegate calculations to domain layer and
+data access to repository implementations.
+"""
+
+from .achievement_service import AchievementService
+from .repositories import AnalyticsRepository, ScanEvent, UserActivity
+from .retention_service import RetentionService
+from .statistics_service import StatisticsService
+from .streak_service import StreakService
+
+__all__ = [
+    "AchievementService",
+    "AnalyticsRepository",
+    "RetentionService",
+    "ScanEvent",
+    "StatisticsService",
+    "StreakService",
+    "UserActivity",
+]