raxe 0.4.6__py3-none-any.whl

raxe/infrastructure/telemetry/__init__.py

@@ -0,0 +1,79 @@
+"""Privacy-first telemetry infrastructure.
+
+Telemetry that respects user privacy by design:
+- Only sends hashes, never actual text
+- No PII is ever transmitted
+- User controls opt-in/opt-out
+- Batch sending for efficiency
+- Graceful degradation on errors
+"""
+
+from raxe.infrastructure.telemetry.credential_store import (
+    CredentialError,
+    CredentialExpiredError,
+    Credentials,
+    CredentialStore,
+    InvalidKeyFormatError,
+    validate_key_format,
+)
+from raxe.infrastructure.telemetry.hook import TelemetryConfig, TelemetryHook, hash_text
+from raxe.infrastructure.telemetry.queue import (
+    EventPriority,
+    EventQueue,
+    QueuedEvent,
+)
+from raxe.infrastructure.telemetry.dual_queue import (
+    DualQueue,
+    StateKey,
+)
+from raxe.infrastructure.telemetry.flush_scheduler import (
+    FlushConfig,
+    FlushScheduler,
+    HttpShipper,
+    SQLiteDualQueueAdapter,
+)
+from raxe.infrastructure.telemetry.health_client import (
+    AuthenticationError,
+    HealthCheckError,
+    HealthResponse,
+    NetworkError,
+    ServerError,
+    TimeoutError,
+    check_health,
+    check_health_async,
+)
+
+__all__ = [
+    # Hook (existing)
+    "TelemetryConfig",
+    "TelemetryHook",
+    "hash_text",
+    # Credential store
+    "CredentialStore",
+    "Credentials",
+    "CredentialError",
+    "CredentialExpiredError",
+    "InvalidKeyFormatError",
+    "validate_key_format",
+    # Event queue
+    "EventQueue",
+    "QueuedEvent",
+    "EventPriority",
+    # Dual queue
+    "DualQueue",
+    "StateKey",
+    # Flush scheduler
+    "FlushConfig",
+    "FlushScheduler",
+    "HttpShipper",
+    "SQLiteDualQueueAdapter",
+    # Health client
+    "HealthCheckError",
+    "AuthenticationError",
+    "NetworkError",
+    "ServerError",
+    "TimeoutError",
+    "HealthResponse",
+    "check_health",
+    "check_health_async",
+]

raxe/infrastructure/telemetry/acquisition.py

@@ -0,0 +1,179 @@
+"""Acquisition source detection for telemetry.
+
+This module handles detection of how RAXE was acquired/installed.
+Contains I/O operations (environment variable reads) so belongs in infrastructure layer.
+"""
+
+import os
+from typing import Literal
+
+AcquisitionSource = Literal[
+    "pip_install",
+    "github_release",
+    "docker",
+    "homebrew",
+    "website_download",
+    "referral",
+    "enterprise_deploy",
+    "ci_integration",
+    "unknown",
+]
+
+# Environment variables that indicate CI environments
+CI_ENV_VARS = frozenset({
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "TRAVIS",
+    "JENKINS_URL",
+    "BUILDKITE",
+    "AZURE_PIPELINES",
+    "BITBUCKET_PIPELINES",
+    "TEAMCITY_VERSION",
+    "DRONE",
+    "CODEBUILD_BUILD_ID",
+})
+
+
+def _is_ci_environment() -> bool:
+    """Check if running in a CI environment.
+
+    Returns:
+        True if any CI environment variable is set.
+    """
+    return any(os.environ.get(var) for var in CI_ENV_VARS)
+
+
+def _is_docker_environment() -> bool:
+    """Check if running inside a Docker container.
+
+    Returns:
+        True if Docker environment is detected.
+    """
+    # Check for Docker-specific environment variable
+    if os.environ.get("RAXE_DOCKER"):
+        return True
+
+    # Check for /.dockerenv file (common Docker indicator)
+    if os.path.exists("/.dockerenv"):
+        return True
+
+    # Check cgroup for docker
+    try:
+        with open("/proc/1/cgroup", "r") as f:
+            return "docker" in f.read()
+    except (FileNotFoundError, PermissionError, OSError):
+        pass
+
+    return False
+
+
+def _has_referral_code() -> bool:
+    """Check if a referral code is present.
+
+    Returns:
+        True if RAXE_REFERRAL_CODE environment variable is set.
+    """
+    return bool(os.environ.get("RAXE_REFERRAL_CODE"))
+
+
+def _is_enterprise_deploy() -> bool:
+    """Check if this is an enterprise deployment.
+
+    Returns:
+        True if RAXE_ENTERPRISE_DEPLOY environment variable is set.
+    """
+    return bool(os.environ.get("RAXE_ENTERPRISE_DEPLOY"))
+
+
+def _get_explicit_acquisition_source() -> str | None:
+    """Get explicitly set acquisition source from environment.
+
+    Returns:
+        The value of RAXE_ACQUISITION_SOURCE if set, None otherwise.
+    """
+    return os.environ.get("RAXE_ACQUISITION_SOURCE")
+
+
+def detect_acquisition_source(
+    install_method: str | None = None,
+) -> AcquisitionSource:
+    """Detect how RAXE was acquired/installed.
+
+    Detection priority (highest to lowest):
+    1. Explicit RAXE_ACQUISITION_SOURCE environment variable
+    2. Enterprise deployment (RAXE_ENTERPRISE_DEPLOY)
+    3. Referral code (RAXE_REFERRAL_CODE)
+    4. Docker environment
+    5. CI environment
+    6. Install method inference (pip -> pip_install)
+    7. Default to "unknown"
+
+    Args:
+        install_method: The install method detected (pip, uv, etc).
+            Used to infer acquisition source if not explicitly set.
+
+    Returns:
+        The detected acquisition source.
+
+    Example:
+        >>> # In normal pip install
+        >>> detect_acquisition_source(install_method="pip")
+        'pip_install'
+
+        >>> # In CI with pip
+        >>> os.environ["CI"] = "true"
+        >>> detect_acquisition_source(install_method="pip")
+        'ci_integration'
+    """
+    # 1. Check for explicit acquisition source
+    explicit_source = _get_explicit_acquisition_source()
+    if explicit_source:
+        # Validate it's a known value
+        valid_sources: set[AcquisitionSource] = {
+            "pip_install",
+            "github_release",
+            "docker",
+            "homebrew",
+            "website_download",
+            "referral",
+            "enterprise_deploy",
+            "ci_integration",
+            "unknown",
+        }
+        if explicit_source in valid_sources:
+            return explicit_source  # type: ignore[return-value]
+
+    # 2. Check for enterprise deployment
+    if _is_enterprise_deploy():
+        return "enterprise_deploy"
+
+    # 3. Check for referral code
+    if _has_referral_code():
+        return "referral"
+
+    # 4. Check for Docker environment
+    if _is_docker_environment():
+        return "docker"
+
+    # 5. Check for CI environment
+    if _is_ci_environment():
+        return "ci_integration"
+
+    # 6. Infer from install method
+    if install_method:
+        # Map install methods to acquisition sources
+        install_method_mapping: dict[str, AcquisitionSource] = {
+            "pip": "pip_install",
+            "uv": "pip_install",  # uv is a pip-compatible installer
+            "pipx": "pip_install",  # pipx installs from PyPI
+            "poetry": "pip_install",  # poetry installs from PyPI
+            "conda": "pip_install",  # Treat conda similar to pip
+            "source": "github_release",  # Source install usually from GitHub
+        }
+        if install_method in install_method_mapping:
+            return install_method_mapping[install_method]
+
+    # 7. Default to unknown
+    return "unknown"

raxe/infrastructure/telemetry/config.py

@@ -0,0 +1,254 @@
+"""
+Telemetry configuration management.
+
+Loads telemetry configuration from schema-validated sources with
+environment variable overrides for privacy control.
+"""
+
+import json
+import logging
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RetryPolicyConfig:
+    """Retry policy configuration."""
+    max_retries: int = 10
+    initial_delay_ms: int = 1000
+    max_delay_ms: int = 512000  # 512s max per specification
+    backoff_multiplier: float = 2.0
+    retry_on_status: list[int] = field(default_factory=lambda: [429, 500, 502, 503, 504])
+
+
+@dataclass
+class TelemetryConfig:
+    """
+    Telemetry configuration with privacy-first defaults.
+
+    All fields match schemas/v1.0.0/config/telemetry_config.json
+    """
+    # Core settings
+    enabled: bool = True
+    endpoint: str = ""  # Will be resolved from centralized endpoints
+    privacy_mode: str = "strict"  # strict, standard, detailed
+
+    # Privacy settings
+    include_full_prompts: bool = False  # NEVER true by default
+    include_context: bool = True
+    hash_algorithm: str = "sha256"
+
+    # Batching settings
+    batch_size: int = 100
+    flush_interval_ms: int = 5000
+    max_queue_size: int = 10000
+
+    # Performance settings
+    sample_rate: float = 1.0
+    compression: str = "gzip"
+    send_performance_metrics: bool = True
+    send_error_reports: bool = True
+
+    # Retry policy
+    retry_policy: RetryPolicyConfig = field(default_factory=RetryPolicyConfig)
+
+    # Custom metadata
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_file(cls, config_path: Path) -> "TelemetryConfig":
+        """
+        Load configuration from JSON file.
+
+        Args:
+            config_path: Path to configuration file
+
+        Returns:
+            TelemetryConfig instance
+        """
+        if not config_path.exists():
+            logger.warning(f"Config file not found: {config_path}, using defaults")
+            return cls()
+
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+                return cls.from_dict(data)
+        except Exception as e:
+            logger.error(f"Failed to load config from {config_path}: {e}")
+            return cls()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TelemetryConfig":
+        """
+        Create configuration from dictionary.
+
+        Args:
+            data: Configuration dictionary
+
+        Returns:
+            TelemetryConfig instance
+        """
+        # Extract retry policy if present
+        retry_policy_data = data.pop("retry_policy", {})
+        retry_policy = RetryPolicyConfig(**retry_policy_data)
+
+        # Create config with remaining fields
+        config = cls(retry_policy=retry_policy)
+
+        # Update with provided values
+        for key, value in data.items():
+            if hasattr(config, key):
+                setattr(config, key, value)
+
+        return config
+
+    @classmethod
+    def from_environment(cls) -> "TelemetryConfig":
+        """
+        Load configuration from environment variables.
+
+        Environment variables override file configuration:
+        - RAXE_TELEMETRY_ENABLED: true/false
+        - RAXE_TELEMETRY_ENDPOINT: URL
+        - RAXE_TELEMETRY_PRIVACY_MODE: strict/standard/detailed
+        - RAXE_TELEMETRY_SAMPLE_RATE: 0.0-1.0
+        - etc.
+
+        Returns:
+            TelemetryConfig instance
+        """
+        config = cls()
+
+        # Map environment variables to config fields
+        env_mapping = {
+            "RAXE_TELEMETRY_ENABLED": ("enabled", lambda x: x.lower() == "true"),
+            "RAXE_TELEMETRY_ENDPOINT": ("endpoint", str),
+            "RAXE_TELEMETRY_PRIVACY_MODE": ("privacy_mode", str),
+            "RAXE_TELEMETRY_INCLUDE_PROMPTS": ("include_full_prompts", lambda x: x.lower() == "true"),
+            "RAXE_TELEMETRY_INCLUDE_CONTEXT": ("include_context", lambda x: x.lower() == "true"),
+            "RAXE_TELEMETRY_HASH_ALGORITHM": ("hash_algorithm", str),
+            "RAXE_TELEMETRY_BATCH_SIZE": ("batch_size", int),
+            "RAXE_TELEMETRY_FLUSH_INTERVAL_MS": ("flush_interval_ms", int),
+            "RAXE_TELEMETRY_MAX_QUEUE_SIZE": ("max_queue_size", int),
+            "RAXE_TELEMETRY_SAMPLE_RATE": ("sample_rate", float),
+            "RAXE_TELEMETRY_COMPRESSION": ("compression", str),
+            "RAXE_TELEMETRY_SEND_METRICS": ("send_performance_metrics", lambda x: x.lower() == "true"),
+            "RAXE_TELEMETRY_SEND_ERRORS": ("send_error_reports", lambda x: x.lower() == "true"),
+        }
+
+        for env_var, (field_name, converter) in env_mapping.items():
+            value = os.environ.get(env_var)
+            if value is not None:
+                try:
+                    setattr(config, field_name, converter(value))
+                except (ValueError, TypeError) as e:
+                    logger.warning(f"Invalid value for {env_var}: {value} ({e})")
+
+        # Handle retry policy from environment
+        retry_env_mapping = {
+            "RAXE_TELEMETRY_MAX_RETRIES": ("max_retries", int),
+            "RAXE_TELEMETRY_INITIAL_DELAY_MS": ("initial_delay_ms", int),
+            "RAXE_TELEMETRY_MAX_DELAY_MS": ("max_delay_ms", int),
+            "RAXE_TELEMETRY_BACKOFF_MULTIPLIER": ("backoff_multiplier", float),
+        }
+
+        for env_var, (field_name, converter) in retry_env_mapping.items():
+            value = os.environ.get(env_var)
+            if value is not None:
+                try:
+                    setattr(config.retry_policy, field_name, converter(value))
+                except (ValueError, TypeError) as e:
+                    logger.warning(f"Invalid value for {env_var}: {value} ({e})")
+
+        return config
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> "TelemetryConfig":
+        """
+        Load configuration with cascading precedence.
+
+        Precedence (highest to lowest):
+        1. Environment variables
+        2. Config file (if provided)
+        3. Default values
+
+        Args:
+            config_path: Optional path to config file
+
+        Returns:
+            Merged configuration
+        """
+        # Start with defaults
+        if config_path and config_path.exists():
+            config = cls.from_file(config_path)
+        else:
+            config = cls()
+
+        # Override with environment variables
+        env_config = cls.from_environment()
+
+        # Merge environment overrides
+        for field_name in config.__dataclass_fields__:
+            env_value = getattr(env_config, field_name)
+            default_value = cls().__dict__[field_name]
+
+            # Only override if environment provided a non-default value
+            if env_value != default_value:
+                setattr(config, field_name, env_value)
+
+        # Validate privacy settings
+        config._validate_privacy()
+
+        logger.info(
+            f"Telemetry config loaded: enabled={config.enabled}, "
+            f"privacy_mode={config.privacy_mode}, endpoint={config.endpoint}"
+        )
+
+        return config
+
+    def _validate_privacy(self) -> None:
+        """Validate and enforce privacy constraints."""
+        # NEVER allow full prompts in strict mode
+        if self.privacy_mode == "strict":
+            if self.include_full_prompts:
+                logger.warning("Disabling include_full_prompts in strict privacy mode")
+                self.include_full_prompts = False
+
+        # Warn about dangerous settings
+        if self.include_full_prompts:
+            logger.warning(
+                "WARNING: include_full_prompts is enabled. "
+                "This will send actual prompt text to telemetry endpoint. "
+                "This is NOT recommended for production use."
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        data = asdict(self)
+        # Convert retry policy dataclass to dict
+        data["retry_policy"] = asdict(self.retry_policy)
+        return data
+
+    def is_enabled(self) -> bool:
+        """Check if telemetry is enabled."""
+        return self.enabled
+
+    def should_sample(self) -> bool:
+        """
+        Check if current event should be sampled.
+
+        Returns:
+            True if event should be sent (based on sample_rate)
+        """
+        if self.sample_rate >= 1.0:
+            return True
+        if self.sample_rate <= 0.0:
+            return False
+
+        import random
+        return random.random() < self.sample_rate